# wellington
Wellington is a lightweight static blog generator written in Rust. You can see
it in action at https://emanuelgeromin.com/blog/
Wellington allows you to write blog posts in markdown and then automatically
- renders them as HTML
- updates the table of contents
- updates the RSS feed.
From the root directory of your website, create a new blog:
```bash
mkdir my-amazing-blog
cd my-amazing-blog
wellington init --title "My Blog" \
--home_url "https://mysite.com \
--desc "My blog about clogs" \
--author "It's Me"
```
Then write a blog post:
```bash
mkdir post-1
touch post-1/index.md # edit this file
wellington sync
```
This last command, `wellington sync`, automatically
- renders the post as HTML at post-1/index.html
- creates/updates the table of contents at index.html
- creates/updates the rss feed at rss.xml
## Installation
Installation is via cargo:
```bash
cargo install wellington
```
## Markdown with Footnotes/Sidenotes
Wellington supports an extended markdown syntax. In addition to the usual
markdown, you can also mark footnotes/sidenotes directly in the HTML using
curly braces:
```markdown
# Here is an article
Here is some text with sidenotes/footnotes{this text will render as a
footnote/sidenote}
```
**Sidenotes** are like footnotes except that they display to the right of the
article instead of the bottom. See [this
blogpost](https://emanuelgeromin.com/blog/intro-reinforcement-learning-tic-tac-toe/)
as an example. To work, they require proper CSS. See the 'CSS'
section below.
## Why Wellington
There are plenty of blogging engines out there, many designed for use with
static hosting services like GitHub pages. One great example is
[Jekyll](https://jekyllrb.com/).
I wrote wellington because I wanted support for sidenotes and require only a
very simple set of features.
## Relative links
Relative links in the post markdown files are automatically changed to point to the directory they're in. So for example, if `my-amazing-blog/post-1/index.md` contains the following:
```markdown
```
Then this is rendered as:
```html
<img src="my-amazing-blog/post-1/image.png" />
```
This makes embedding images in the blog post easier.
## CSS
Wellington's sidenotes were designed for use with
[tufte-css](https://github.com/edwardtufte/tufte-css). I use a modified version on [my blog](https://emanuelgeromin.com/blog/tufte.css). This modified version is more mobile friendly and on narrow screens, instead of displaying sidenotes, displays footnotes. You're very welcome to copy my CSS. Alternatively, as a more minimal solution, you can just hide the sidenotes if you don't require them and render only the footnotes:
```css
.sidenote {
display: none;
}
```
To display the blog posts in a mobile friendly way, by using sidenotes for desktop and footnotes for mobile, as I've done, please
check the [modified version of tufte-css](https://emanuelgeromin.com/blog/tufte.css).
## Templates
To render the posts and the table of contents, wellington uses
[Handlebars](https://github.com/sunng87/handlebars-rust), a templating engine.
This allows for customisability of the posts and of the table of contents.
There are default templates in the source code in the `templates` directory.
These are used by default and do not require installation. To override them,
provide your own templates in your blog home directory:
- `.index_template.html` for the table of contents
- `.post_template.html` for the posts
Take a look at the default templates and adapt them to suit your needs!
## MathJax (Latex) support
Using mathjax (latex) in the blog posts requires a hack. To prevent the latex
to be rendered by the markdown parser, it has to be marked as code in markdown,
for example
```markdown
# a markdown file
Here is some text with an equation: `\(E = mc^2\)`
```
By default, mathjax does not render anything wrapped in `<pre>`
or `<code>` tags. To override this behaviour,
in addition to the `<script>` tag linking to the mathjax CDN, you will have to add
the following to your template `<head>` section:
```html
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
tex2jax: {
skipTags: ["script","noscript","style","textarea"]
}
});
</script>
```
This overrides the default `skipTags`, allowing also latex in `<pre>` and
`<code>` tags to be rendered.
If you require both rendered latex and latex code in your blog posts, then
unfortunately at the moment you're out of luck. A more long term solution would
be to parse latex properly in the markdown document. However, this is a more
long term project as it requires modifying `pulldown-cmark`, the library I use
for rendering markdown. Contributions are welcome!
## Known Bugs
- Footnotes are not rendered properly as all inline markdown formatting is lost
(#3)
## Roadmap
There is still much to do. The current codebase grew organically without much
advance planning. This shows: the codebase is quite messy and in need of a
refactor!
Feature wise, soon I hope to support
- syntax highlighting (#1)
- make the template variables `post_url` and `index_url` available in the
markdown as well (#5). This is useful when embedding external code or demos in the
blog post.