@def hascode = true
# Templates
\blurb{Start from one of the template or build your own.}
\lineskip
\toc
\lineskip
The pre-defined templates that are currently available in Franklin with the `newsite` function can be viewed ~~~here~~~ (_opens in a new tab_).
## Adapting a theme to Franklin
\note{If you end up doing this, please consider making a PR to [FranklinTemplates](https://github.com/tlienart/FranklinTemplates.jl)!}
On this page, I'll take [Jemdoc's website layout](http://jemdoc.jaboc.net/) and show how it can be adapted to be a working Franklin template.
This will hopefully also show you how to adapt / modify an existing template.
Jemdoc's layout looks like this:
### Getting started
In order to get a blueprint for the folder etc, let's first create a Franklin site with 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 `_css/` and adjust the layout part in `_layout/`.
### Adapting the head and foot
The file `_html_parts/head.html` is the most important one you will have to adjust.
Let us first change the name of the main stylesheet `_css/basic.css` to `_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 following step is fairly simple:
@@tlist
1. look at the original html code,
2. copy whatever is relevant that 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 Franklin 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
By now the page looks pretty bad:
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 `_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 `franklin.css`, don't change that for now; note also that `jemdoc.css` is loaded *after* `franklin.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 helps a lot:
A few things should be fixed:
@@tlist
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.
First, 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 `franklin-content` element:
```css
.franklin-content { padding-left: 5%; }
```
Finally, 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, in general, you might want to adjust the other pages:
@@tlist
* `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 `.franklin-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!
Please follow [these instructions](https://github.com/tlienart/FranklinTemplates.jl#fixingadding-a-template).