From a8be1400ee4746e0ff1605a43a902468b8a7b750 Mon Sep 17 00:00:00 2001
From: luke-strange <92686634+luke-strange@users.noreply.github.com>
Date: Fri, 6 Sep 2024 17:26:56 +0100
Subject: [PATCH] Update docs

---
 src/_includes/content/description.vto | 18 ++++++++++++++++++
 src/index.vto                         | 21 +++++----------------
 2 files changed, 23 insertions(+), 16 deletions(-)
 create mode 100644 src/_includes/content/description.vto

diff --git a/src/_includes/content/description.vto b/src/_includes/content/description.vto
new file mode 100644
index 0000000..148bae9
--- /dev/null
+++ b/src/_includes/content/description.vto
@@ -0,0 +1,18 @@
+<h3>Why?</h3>
+<p>
+    This tool was born from recent work on our <a href="https://open-innovations.github.io/housing/">housing site</a> where we started
+    <a href="https://open-innovations.github.io/housing/data/explorations/">documenting some of our code</a> using 
+    jupyter notebooks. In summary:
+    <ul>
+        <li>If you have a <code>jupyter notebook</code> and you want to put it on a <code><a href="/">Lume</a></code> site, you need to convert it to a format <code>Lume</code> knows about.</li>
+        <li>You can automatically convert notebooks to <code>markdown</code> with <code>jupyter <a href="https://nbconvert.readthedocs.io/en/latest/usage.html">nbconvert</a></code>. </li> 
+        <li>However, if you then want to include other elements like <code><a href="https://open-innovations.github.io/oi-lume-viz/samples/">OI Lume charts</a></code> or parts of other pages using <code>{{ "{{ includes }}" |> escape }}</code> tags, you need a <code><a href="https://vento.js.org/">.vento</a></code> (or <code>.njk</code>) file.</li>
+        <li>This tool converts the <code>markdown</code> format to <code>vento</code>, preserving things like front matter, and various <code>HTML</code> tags. It adds <code>{{ "<p>" |> escape }}</code> tags to sentences and formats any code blocks correctly so that they can be styled using the <code><a href="https://lume.land/plugins/prism/">prism</a></code> plugin. </li>
+    </ul>
+</p>
+<h3>How to use:</h3>
+<p>
+    First, convert your notebook using the command line: <code>jupyter nbconvert your_notebok.ipynb --to markdown</code>.
+    The output will be saved in your current working directory. Then use this tool to convert the markdown to vento.
+</p>
+
diff --git a/src/index.vto b/src/index.vto
index 1af999e..9b68a84 100644
--- a/src/index.vto
+++ b/src/index.vto
@@ -1,20 +1,9 @@
 ---
-title: Markdown to Vento Converter
+title: 
 ---
-<p>
-    On our <a href="https://open-innovations.github.io/housing/">housing site</a> we recently started 
-    <a href="https://open-innovations.github.io/housing/data/explorations/">documenting some of our code</a> using 
-    jupyter notebooks. It's easy to convert these to markdown format using <code>jupyter nbconvert</code>, and Lume 
-    supports markdown as a template format. This worked fine until we wanted to put <a href="https://open-innovations.github.io/oi-lume-viz/samples/">
-    OI Lume charts</a> onto those pages as well. At this point, we needed to convert the files to Vento to allow us to load 
-    the charts and maintain the styling for the code blocks. This was a tedious manual process, so we made a tool to do it for us. 
-    This programme runs in the browser - nothing ever leaves your computer.
-</p>
-<p>
-    First, convert your notebook using the command line: <code>jupyter nbconvert your_notebok.ipynb --to markdown</code>.
-    The output will be saved in your current working directory. <a href="https://nbconvert.readthedocs.io/en/latest/usage.html">Read the docs</a>
-     for more detailed info. Then use this tool to convert the markdown to vento.
-</p>
+
+{{ include 'content/description.vto' }}
+
 <div id="drop-area">
     <p>Drop a markdown file here</p>
     <p>or</p>
@@ -22,5 +11,5 @@ title: Markdown to Vento Converter
 </div>
 
 <p class="padded"><a id="download-link" download="converted.vto">Download Converted File</a></p>
-
+<p class='warning padded centred'>This programme runs in the browser - nothing ever leaves your computer.</p>
 <script src="/assets/js/app.js"></script>