starting to work on #136 along with general doc fixes

docs/make.jl

@@ -16,7 +16,8 @@ makedocs(
              "Workflow" => "man/workflow.md",
              "Syntax" => "man/syntax.md",
              "Templating" => "man/templating.md",
-             "Contributing" => "man/contrib.md"
+             "Themes" => "man/themes.md"
+             "Contributing" => "man/contrib.md",
             ],
         "Library" => [
             "Design"    => "lib/design.md",

docs/src/man/syntax.md

@@ -85,7 +85,8 @@ b &=& 7 \end{eqnarray}
     Currently all display-math equations are numbered by default.
 
 A final element to keep in mind is that you should surround inequality operators with whitespaces in order to avoid ambiguous commands in KaTeX.
-So in particular, both: `$0< C$` or `$0 < C$` are fine but `0 <C` isn't.
+So in particular, both: `$0< C$` or `$0 < C$` are fine but `$0 <C$` isn't.
+When in doubts add whitespaces.
 
 ### Div blocks
 
@@ -130,7 +131,7 @@ Some text here in the "standard" layout then you can inject raw HTML:
 ~~~
 <div class="row">
   <div class="container">
-    <img class="left" src="assets/infra/rndimg.jpg">
+    <img class="left" src="/assets/infra/rndimg.jpg">
     <p> Marine iguanas are truly splendid creatures. </p>
     <p> Evolution is cool. </p>
     <div style="clear: both"></div>      
@@ -143,7 +144,7 @@ and subsequently continue with the standard layout.
 
 !!! note
 
-    In a raw HTML, you cannot use markdown, maths etc. For this reason, it is often preferable to use nested `@@divname...` blocks instead of raw HTML since those _can_ have markdown, maths, etc. in them.
+    In a raw HTML, you cannot use markdown, maths etc. For this reason, it is often preferable to use nested `@@divname...` blocks instead of raw HTML since those _can_ have markdown, maths, etc. in them. (See also the example generated by [`newsite`](@ref).)
 
 ### Comments
 
@@ -193,7 +194,7 @@ Let $f:\R\to\R$ a function...
 **Example 3**: a command to change the colour of the text outside of a math environment (note that inside a math environment you can use `\textcolor` which is defined in KaTeX; I'm using a different name here so that these two don't clash since commands defined in JuDoc take precedence):
 
 ```judoc
-\newcommand{\col}[2]{~~~ <font color="#1">#2</font> ~~~}
+\newcommand{\col}[2]{~~~ <span style="color:#1">#2</span> ~~~}
 
 And then you can use \col{tomato}{colours} in your text and
 $$x + \textcolor{blue}{y} + z$$
@@ -206,7 +207,7 @@ in your maths.
 
 ### Nesting
 
-Using commands can be nested, again as in LaTeX and, moreover, you can throw in some markdown.
+Using commands can be nested --as in LaTeX-- and, moreover, you can throw in some judoc markdown.
 Here is a somewhat more sophisticated example for a "definition" environment:
 
 ```judoc
@@ -304,7 +305,8 @@ As in LaTeX, you can refer to several equations in one by separating names with
 For bibliography references, you can use `\biblabel{short}{name}` to indicate a bibliography reference which will appear as a clickable link `(name)` or `name` and can be referred to by `short`:
 
 ```judoc
-In the text you may refer to \citep{noether15, bezanson17} while in a bibliography section you would have
+In the text you may refer to \citep{noether15, bezanson17} while in a bibliography
+section you would have
 
 * \biblabel{noether15}{Noether (1915)} **Noether**, Korper und Systeme rationaler Funktionen, 1915.
 * \biblabel{bezanson17}{Bezanson et al. (2017)} **Bezanson**, **Edelman**, **Karpinski** and **Shah**, [Julia: a fresh approach to numerical computing](https://julialang.org/publications/julia-fresh-approach-BEKS.pdf), SIAM review 2017.
@@ -322,6 +324,8 @@ You can use
 * `\cite{short1, short2}` or `\citet{short3}`: will not add parentheses around the link(s),
 * `\citep{short4, short5}`: will add parentheses around the link(s).
 
+As in LaTeX, if the reference is undefined, the command will be replaced by **(??)**.
+
 !!! note
 
     In the future, there may be a possibility to define specific bibliography styles.
@@ -332,7 +336,7 @@ You can use
 Sometimes, when presenting code in a post, you would like to make sure the code works and it can be annoying to have to copy-paste it around then copy its output, especially if you decide to make modifications on the way in which case you have to repeat the process.
 For this reason, insertions can be convenient. The philosophy is:
 
-* keep your code snippets in `assets/scripts` where they can be run and their output can be saved, this can be compared to a `test/` folder in a Julia package,
+* keep your code snippets in `assets/scripts` (or subfolders) where they can be run and their output can be saved, this can be compared to a `test/` folder in a Julia package,
 * run some or all of the snippets,
 * use `\input{...}{...}` in your markdown (see below) and when the website is updated, it will plug-in the most recent parts that have been generated.
 
@@ -355,21 +359,22 @@ The folder structure for `assets/scripts` should resemble
 .
 └──scripts
     ├── generate_results.jl
-    ├── output
+    ├── output              # generated
     │   ├── script1.txt
     │   └── script2.png
     ├── script1.jl
     └── script2.jl
 ```
 
-Your scripts would be `script1.jl` and `script2.jl` these can contain `# hide` at the end of lines you do not want to show (`hide` is not case sensitive so `# HiDe` would be fine too).
+Your scripts would be `script1.jl` and `script2.jl` (these can be in subfolders of `scripts/` as well).
+
+The script files can contain `# hide` at the end of lines you do not want to show (`hide` is not case sensitive so `# HiDe` would be fine too).
 
 The `generate_results.jl` file should run the scripts and redirect outputs to the `assets/scripts/output` directory.
-We suggest you use something like this (if you generate an example website with [`newsite`](@ref), it's all in there) though you can of course modify it as you wish.
+You can use something like the script below (if you generate an example website with [`newsite`](@ref), it's already in there) though you can of course modify it as you wish.
 
 ```julia
 dir = @__DIR__
-
 """
     genplain(s)
 
@@ -382,10 +387,8 @@ function genplain(s::String)
         end
     end
 end
-
 # run `script1.jl` and redirect what it prints to `output/script1.txt`
 genplain("script1.jl")
-
 # run `script2.jl` which has a savefig(joinpath(@__DIR__, "output", "script2.png"))
 include("script2.jl")
 ```

docs/src/man/templating.md

@@ -55,7 +55,7 @@ Here the `fill` function simply tries to find a page variable `"title"` and plac
 <title>Title for page 1</title>
 ```
 
-See [Function blocks](#Function-blocks-1) for more such functions that can be used.
+See [function blocks](#Function-blocks-1) for additional such functions that can be used.
 
 !!! note
 
@@ -64,15 +64,17 @@ See [Function blocks](#Function-blocks-1) for more such functions that can be us
 ## Conditional blocks
 
 It will often be handy to do things in your layout conditional on specific variables.
+For instance you may want to highlight elements in your navbar depending on which page you're on.
+
 Three types of conditional blocks are allowed:
 
 * a "classical" conditional block with `if`, `elseif`, `else` that accepts page variables that have boolean value,
 * a conditional block that does something provided a variable exists (or not),
-* a conditional block that does something depending on whether the page is a specific one (or not a specific one).
+* a conditional block that does something depending on whether the page is a specific one (or not).
 
 !!! note
 
-    Nesting of conditional blocks is currently **not allowed**  but shouldn't be hard to implement and will likely be supported in the near future.
+    Nesting of conditional blocks is currently **not allowed**  but shouldn't be hard to implement and will likely be supported in the future.
 
 ### Base conditional blocks
 
@@ -149,7 +151,7 @@ which add a class to a `<li>` object depending on the page that indicate which l
 
 !!! note
 
-    As the def blocks above, these blocks do not yet accept `{{else}}` statements.
+    As for the def blocks above, these blocks do not yet accept `{{else}}` statements.
 
 ## Function blocks
 

docs/src/man/themes.md

@@ -0,0 +1,10 @@
+# Themes
+
+```@raw html
+The pre-defined themes/templates that are currently available can be viewed <a href="https://tlienart.github.io/JuDocTemplates.jl/" target="_blank" rel="noopener noreferrer">here</a> (opens in a new tab).
+```
+
+In this section, you will learn how to build a template from one online.
+Assuming you're happy with the result, a PR to [JuDocTemplates](https://github.com/tlienart/JuDocTemplates.jl) would be very welcome!
+
+## Adapting a theme to JuDoc

docs/src/man/workflow.md

@@ -12,7 +12,7 @@ In this section it is assumed that you will eventually host your website on GitH
 * [Optimisation step](#Optimisation-step-1)
 * [(git) synchronisation](#(git)-synchronisation-1)
   * [Merge conflicts](#Merge-conflicts-1)
-* [Literate programming (and blogging) with Literate.jl](#Literate-programming-(and-blogging)-with-Literate.jl-1)
+* [Using Literate.jl](#Using-Literate.jl-1)
 
 ## Local editing
 
@@ -131,35 +131,37 @@ While this will be imperceptible if you only have a few light assets, it could s
 
 ## Libraries
 
-If you used the [`newsite`](@ref) function to get started, then you should have a `libs/` folder with
+Assuming you used the [`newsite`](@ref) function to get started, you have a `libs/` folder with
 
 ```
 .
 ├── highlight/
 └── katex/
 ```
 
-If you require other libraries to run your website, this is where you should put them while not forgetting to load them in your `_html_parts`; for instance in `foot_highlight.html` you will find:
+If you require other libraries to run your website, this is where you should put them while not forgetting to load them in your `_html_parts`; for instance in the default `foot_highlight.html` you will find:
 
 ```html
 <script src="/libs/highlight/highlight.pack.js"></script>
 <script>hljs.initHighlightingOnLoad();hljs.configure({tabReplace: '    '});</script>
 ```
 
+which loads and applies `highlight.js`.
+
 ### Highlight
 
-If you used the [`newsite`](@ref) command then the `libs/highlight/` folder contains
+Assuming you used the [`newsite`](@ref) function to get started, you have the `libs/highlight/` folder with
 
 ```
 .
 ├── github.min.css
 └── highlight.pack.js
 ```
 
-Of course if you want to change either how things look or which languages are supported, you should head to [highlightjs.org](https://highlightjs.org/download/), select the languages you want in the **Custom package** section, download the bundle and copy over the relevant files to `libs/highlight/`.
+If you want to change either how things look or which languages are supported, you should head to [highlightjs.org](https://highlightjs.org/download/), select the languages you want in the **Custom package** section, download the bundle and copy over the relevant files to `libs/highlight/`.
 By default, `bash`, `html/xml`, `python`, `julia`, `julia-repl`, `css`, `r`, `markdown`, `ini/TOML`, `ruby` and `yaml` are supported.
 
-Just remember to refer to the appropriate style-sheet in your HTML building blocks for instance `src/_html_parts/head_highlight.html`:
+Just remember to refer to the appropriate style-sheet in your HTML building blocks for instance the default `src/_html_parts/head_highlight.html` contains:
 
 ```html
 <link rel="stylesheet" href="/libs/highlight/github.min.css">
@@ -190,7 +192,7 @@ That step can:
 
 Those steps (which you can opt out of using the appropriate keyword `prerender=false` or `minify=false`) may lead to faster loading pages.
 
-In order to run this optimisation step, you will need some [Dependencies](#Dependencies-1) but if you don't have them, JuDoc will tell you and ignore the corresponding step.
+In order to run this optimisation step, you will need some [dependencies](/#External-dependencies-1) but if you don't have them, JuDoc will tell you and ignore the corresponding step.
 Note also that doing a full pass of pre-rendering and minifying may take a few seconds depending on how many pages you have.
 
 ## (git) synchronisation
@@ -238,7 +240,9 @@ serve()
 publish()
 ```
 
-## Literate programming (and blogging) with Literate.jl
+## Using Literate.jl
+
+(_Thanks to [@cormullion](https://github.com/cormullion) for this section_)
 
 You can use Fredrik Ekre's [Literate.jl](https://github.com/fredrikekre/Literate.jl) package to create Markdown pages suitable for including in your JuDoc workflow. Literate.jl lets you write everything in a Julia source file, including your code, comments, tests, generated plots, and so on. When you execute the Julia file, all your code runs, and you can arrange for Literate.jl to write output such as Markdown-formatted text (and/or Jupyter notebooks) to suitable files.
 Literate.jl's syntax relies on various different flavours of comment, some of which are shown in the simple example below.
@@ -249,6 +253,7 @@ You can see the `>` Markdown quote syntax and the `##` Markdown header level 2 s
 Lines preceded by `#jl` are not included in the Markdown output.
 Lines ending with `#src` are evaluated when you run the Julia file, but are not copied into the Markdown output file.
 Lines beginning with `#src` are Julia comments that don't make it as far as the Markdown file.
+Refer to [Literate.jl's docs](https://fredrikekre.github.io/Literate.jl/stable/) for more information.
 
 You can see from the final five lines in the example that, when you run this file in Julia, the final step is to run the `Literate.markdown` function, taking the name of the Julia source file (`functionoftheweek.jl`) as input, and writing a new Markdown file to the directory `src/pages/` as `fotw_floorceil.md`.
 Finally, if the JuDoc server is running, you'll find the generated HTML page as `/pub/fotw_floorceil.html`.
@@ -263,7 +268,11 @@ Finally, if the JuDoc server is running, you'll find the generated HTML page as
 
 # ## Function of the week: floorceil()
 
-# Welcome to another weekly post in which I present a cool Julia function that I've just discovered. This week it's the turn of `floorceil()`. It might sound like something that comes in a tin, but in fact it's a useful function in the Dates module that returns two Dates or DateTimes, one before, and one after, the specified time by a certain unit of time.
+# Welcome to another weekly post in which I present a cool Julia function that I've
+# just discovered. This week it's the turn of `floorceil()`. It might sound like
+# something that comes in a tin, but in fact it's a useful function in the Dates module
+# that returns two Dates or DateTimes, one before, and one after, the specified time by
+# a certain unit of time.
 
 # For example:
 
@@ -282,7 +291,8 @@ Dates.floorceil(now(), Dates.Month(1))
 # (2019-05-01T00:00:00, 2019-06-01T00:00:00)
 #
 
-# and you can see that the result contains the beginning and the end of the month that includes the present time of day.
+# and you can see that the result contains the beginning and the end of the month
+# that includes the present time of day.
 
 a, b = (Dates.floorceil(now(), Dates.Month(1)));
 Dates.canonicalize(Dates.CompoundPeriod(b - a))
@@ -313,7 +323,11 @@ Notice that the two JuDoc `@def` lines have survived the journey from Julia to M
 
 ## Function of the week: floorceil()
 
-Welcome to another weekly post in which I present a cool Julia function that I've just discovered. This week it's the turn of `floorceil()`. It might sound like something that comes in a tin, but in fact it's a useful function in the Dates module that returns two Dates or DateTimes, one before, and one after, the specified time by a certain unit of time.
+Welcome to another weekly post in which I present a cool Julia function that I've
+just discovered. This week it's the turn of `floorceil()`. It might sound like
+something that comes in a tin, but in fact it's a useful function in the Dates module
+that returns two Dates or DateTimes, one before, and one after, the specified time by
+a certain unit of time.
 
 For example:
 
@@ -331,7 +345,8 @@ Dates.floorceil(now(), Dates.Month(1))
 
 (2019-05-01T00:00:00, 2019-06-01T00:00:00)
 
-and you can see that the result contains the beginning and the end of the month that includes the present time of day.
+and you can see that the result contains the beginning and the end of the month
+that includes the present time of day.
 
 ```julia
 a, b = (Dates.floorceil(now(), Dates.Month(1)));