Create a new post🔗
Sharing ideas and tips is very much welcome, if you like you can
create a small (or large) post here. You'll need
git and potentially
github account to make this convenient.
It is not necessary to know how everything is connected, you only need to edit or create markdown files at some specific location. Here are some proposals how to add or edit pages and getting them published to docspell.org.
Where to create the files🔗
The contents of the published website is in the branch
You should base your changes on this branch.
All blog pages go into this directory:
In this directory each post is a markdown file named by this pattern:
For example, this page here is named
Write on Github🔗
A very convenient way is to edit and create posts directly on github
in the browser. All pages contain a small
Edit link at the bottom
that takes you directly into edit model of the corresponding file on
To create a new file on github, you can use this link:
It will present a form that lets you create a new file with content. Once you commit this change, the project will be forked into your account and the change is applied to this new fork. Then you can create a pull request into this repository in order to publish it.
Plase see below for how to start writing content.
The preferred approach is to explicitely fork the repository and clone it to your machine to do the modification. The big advantage is, that you can look at the results while writing.
If you want to see a live view of the page while editing, some tools
are required. The easiest way to get these is to install
nix and run
nix-shell website/shell.nix to get
an environment with all these tools installed. Otherwise install the
programs mentioned in
website/shell.nix, which are:
elm and sbt.
Then clone the sources to your machine and build the complete site once, so that all assets and required stuff is present:
Now you can use zola to start the page and watch for changes. The changes are visible immediately without reloading the page in the browser.
cd website/site && zola serve
This starts a web server on some port (usually
1111); point your
browser to it and navigate to your new page. Whenever changes are
saved to the markdown file, the page refreshes automatically.
If styling is changed (in the css files or also sometimes when adding
new classes to HTML elements), a rebuild of the site css is necessary.
This can be done by running
scripts/run-styles.sh --watch it is possible to watch for these
changes as well. But it shouldn't be necessary to do large edits to
The very beginning of such a markdown file contains some metadata. Start each page with these lines:
The front matter is the first part enclosed in
documentation for more details.
authorLink setting is optional. You can leave out
[extra] section. If
authorLinkis defined, the author
is rendered as a link to that URL. If
author is missing, it defaults
The content is styled automatically and the post is added to the list on the main blog page. Additional to the standard markdown formatting, there are some more usefull elements.
If you want to link to an internal page, use markdown links where the path is formatted like this:
@/path style, zola generates the correct final link (and
checks for dead links).
Info and warning boxes🔗
There are small templates available to format a basic info or warning box message.
For a box more styled like a warning, replace
This will render into:
Your content here ….
Your content here ….
In order to get a decent summary in the list of posts, you need to set a marker in your file. Place a line containing only
<!-- more -->
into your file and everything before it will be rendered as a summary on the blog listing.
Styled buttons can be created using HTML inside the markdown file:
In image to appear on the whole page, use HTML with a
<figure> <img src="image-url.jpg"> </figure>
The site has a light and dark mode and sometimes it's nice to provide images for both variants. You can use HTML for this and a specific class per theme:
See the effect when changing the theme:
This can be done via a template if the file is next to the markdown file in the same directory:
Open a pull request against the
current-docs branch. When the pull
request is merged, the publishing process starts automatically and the
content is available minutes after.