diff --git a/docs/make.jl b/docs/make.jl
index f66c72be8..71895e469 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -16,7 +16,7 @@ makedocs(
"Workflow" => "man/workflow.md",
"Syntax" => "man/syntax.md",
"Templating" => "man/templating.md",
- "Themes" => "man/themes.md"
+ "Themes" => "man/themes.md",
"Contributing" => "man/contrib.md",
],
"Library" => [
diff --git a/docs/src/assets/jemdoc1.png b/docs/src/assets/jemdoc1.png
new file mode 100644
index 000000000..03a83acd1
Binary files /dev/null and b/docs/src/assets/jemdoc1.png differ
diff --git a/docs/src/assets/jemdoc2.png b/docs/src/assets/jemdoc2.png
new file mode 100644
index 000000000..27e6b396b
Binary files /dev/null and b/docs/src/assets/jemdoc2.png differ
diff --git a/docs/src/assets/jemdoc3.png b/docs/src/assets/jemdoc3.png
new file mode 100644
index 000000000..526d47c0e
Binary files /dev/null and b/docs/src/assets/jemdoc3.png differ
diff --git a/docs/src/assets/jemdoc4.png b/docs/src/assets/jemdoc4.png
new file mode 100644
index 000000000..aaadd20aa
Binary files /dev/null and b/docs/src/assets/jemdoc4.png differ
diff --git a/docs/src/man/themes.md b/docs/src/man/themes.md
index fc5584434..4d49eac6b 100644
--- a/docs/src/man/themes.md
+++ b/docs/src/man/themes.md
@@ -4,7 +4,287 @@
The pre-defined themes/templates that are currently available can be viewed here (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!
+In this section, you will learn how to build a layout from one online.
+It should also help clarify the structure of the files that define the layout.
+If you end up doing this yourself and 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
+
+As an example, I'll take [Jemdoc's site](http://jemdoc.jaboc.net/) both because it's a pretty simple layout and as a way to honour its legacy since JuDoc was inspired from it.
+
+Jemdoc's layout looks like this:
+
+
+
+### Getting started
+
+In order to get a blueprint for the folder etc, let's first create a site according to the `basic` template:
+
+```julia-repl
+julia> newsite("jemdoc", template="basic")
+```
+
+You can serve the site in order to see the modifications directly in your browser which can be useful to fine tune the port of the layout.
+
+We will need to provide the appropriate stylesheet in `src/_css` and adjust the layout part in `src/_html_parts`.
+
+### Adapting the head and foot
+
+The file `src/_html_parts/head.html` is the most important one you will have to adjust.
+
+Let us first change the name of the main stylesheet `src/_css/basic.css` into `src/_css/jemdoc.css` which is more appropriate.
+The reference to the stylesheet in `head.html` consequently has to be changed to mention `jemdoc.css` instead of `basic.css`:
+
+```html
+
+```
+
+The steps here subsequently quite simple:
+
+1. look at the original html code
+2. copy whatever comes before the content into `head.html`
+
+Let's do this gradually.
+The top of the original HTML can be ignored at this point so we can start modifying starting after ``.
+
+Jemdoc's body starts with a Google analytics script which I'll ignore as well.
+We then have effectively one big table element.
+Stripped from its content and simplified it looks like:
+
+```html
+
+```
+
+Note that I've already filled in the `href=` in the links to sub-menus.
+
+The "`CONTENT HERE`" part is where what JuDoc generates from Markdown will go.
+Therefore, anything that is *after* that should go in `foot.html`; in our current case:
+
+```html
+
+
+
+
+```
+
+That's basically it (though we still have to modify the stylesheet of course).
+The `head.html` should be adapted to:
+
+```html
+
+
+
+
+
+ {{if hasmath}} {{insert head_katex.html }} {{end}}
+ {{if hascode}} {{insert head_highlight.html }} {{end}}
+
+
+
+ {{isdef title}} {{fill title}} {{end}}
+
+
+
+
+
+```
+
+and the `foot.html` should be adapted to:
+
+```html
+
+
+
+
+ {{ if hasmath }}
+ {{ insert foot_katex.html }}
+ {{ end }}
+ {{ if hascode }}
+ {{ insert foot_highlight.html }}
+ {{ end }}
+
+
+```
+
+### Adapting the stylesheet
+
+Of course by now the page looks horrendous:
+
+
+
+the content is not centred in its box and overflows on the right, the menu looks ridiculous, time to do some CSS styling!
+
+Let's start by removing everything from `src/_css/jemdoc.css`.
+Most of what's in there was used for the styling of the top navbar which we don't have anymore (note that the styling of the content itself is in `judoc.css`, don't change that for now; note also that `jemdoc.css` is loaded *after* `judoc.css` so that you can overwrite the styles there).
+
+Let's now just copy paste the content of the [two](http://jemdoc.jaboc.net/jemdoc.css) [original](http://jemdoc.jaboc.net/jacob.css) stylesheets into ours and hope for the best, we may have some fine-tuning to do after this.
+
+Doing nothing else than copy pasting already starts to look quite civilised:
+
+
+
+but a few small things should be fixed:
+
+1. there's too little space at the top
+1. the menu is a bit too narrow and there's a bit too much space between the menu and the content
+1. there's not enough space after `
` blocks
+
+#### Fixing spacing
+
+Firefox or Chrome/ium's excellent dev-tools are super helpful to fine tune stylesheets.
+Here things are pretty straightforward though.
+
+Firstly we need to add vertical padding above `
` level title:
+
+```css
+h1 { padding-top: 2em; }
+```
+
+Then, let's widen the menu a little
+
+```css
+td#layout-menu {
+ padding-left: 15px;
+ padding-right: 25px;
+}
+```
+
+and let's reduce the padding on the left of the `jd-content` element:
+
+```css
+.jd-content { padding-left: 5%; }
+```
+
+Thirdly, in the original stylesheet there is this element:
+
+```css
+pre {
+ padding: 0;
+ margin: 0;
+}
+```
+
+which you can just remove to have a bit more space around code blocks.
+
+There's probably still things that could be done to improve the layout overall (and make it more responsive!) but we'll leave it at that.
+
+
+
+### Adjusting other files
+
+Here we don't need to adjust anything else but you could want to adjust the pages in another context:
+
+* `head_highlight`, `head_katex`, `foot_highlight` and `foot_katex` are probably best left as they are, they will be appended if need be to pages (see in `head` and `foot` the `{{if hasmath}}` and `{{if hascode}}` blocks)
+* `page_foot` you may want to change, it defines what goes at the bottom of the `.jd-content` div.
+
+By default `page_foot` looks like
+
+```html
+
+```
+
+It should be fairly straightforward to adapt that to your needs.
+
+## Making a PR to the theme repo
+
+Let's say you've built your own template and are pretty happy with the result and you'd like to share it for other users, great! thanks for being a good citizen.
+
+### Create a new folder
+
+Head to the [JuDocTemplates.jl](https://github.com/tlienart/JuDocTemplates.jl) repository and make a PR.
+The key is to keep track of what you've modified and what was left as before so that the repo is not cluttered with copies of the same file.
+
+In the example above the following files were changed:
+
+* `head.html` and `foot.html`,
+* `jemdoc.css` the stylesheet.
+
+The JuDocTemplates repository automatically fills in the gap so you just have to provide the files that have changed.
+Imitate the structure corresponding to [`basic`](https://github.com/tlienart/JuDocTemplates.jl/tree/master/src/templates/basic/src):
+
+```
+.
+└── src
+ ├── _css
+ │ └── basic.css
+ └── _html_parts
+ └── head.html
+```
+
+So in the case of `jemdoc`, I will create a new folder `jemdoc` in `src/templates/` with
+
+```
+.
+└── src
+ ├── _css
+ │ └── jemdoc.css
+ └── _html_parts
+ ├── foot.html
+ └── head.html
+```
+
+### Add your template to the list
+
+Next, you need to indicate the new template in `JuDocTemplates.jl` by simply adding it to the `LIST_OF_TEMPLATES` constant.
+
+Then, you need to add a description for your template in `docs/make.jl` (please respect the alphabetical order):
+
+```julia
+"jemdoc" => """
+ jemdoc
+
Simple theme with a side navigation bar, no extra javascript and a simple stylesheet. (Adapted from the original Jemdoc theme.)
+ """,
+```
+
+Lastly you need to take a screenshot of what the template looks like of size 480x480, put it in `docs/thumb` and adjust `docs/index_head.html` following the example of the other templates:
+
+```css
+#jemdoc {
+ background: url("thumb/jemdoc.png");
+ background-size: contain;
+}
+```
+
+### Check that things work
+
+Finally, you need to check that everything works (which is the first thing I'll do when reviewing your PR).
+For that: first run the file `docs/make.jl`; this will generate a website in `docs/build` then using for instance [`LiveServer.jl`](https://github.com/asprionj/LiveServer.jl), check the generated website and that the demo corresponding to your template works as expected.
+
+And that's it! thanks a lot!