docspell/website/site/content/blog/2022-01-31_create_post.md

+++ title = "Create a new post" [extra] author = "eikek" +++

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 a github account to make this convenient.

The contents of this website is maintained in the git repository in the website/site folder. It is build by the static site generator zola from a set of markdown files.

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 current-docs. You should base your changes on this branch.

All blog pages go into this directory: website/site/content/blog/. In this directory each post is a markdown file named by this pattern:

<year>-<month>-<day>_title_with_underscores.md

For example, this page here is named 2022-01-31_create_post.md.

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 github.

To create a new file on github, you can use this link:

https://github.com/eikek/docspell/new/current-docs/website/site/content/blog

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.

Writing locally

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 develop .#dev-vm to get an environment with all these tools installed. Otherwise install the programs: yarn, zola, 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:

sbt website/zolaBuildTest

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. Via 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 css.

Content

Front matter

The very beginning of such a markdown file contains some metadata. Start each page with these lines:

+++
title = "Title of the post"
[extra]
author = "<your name>"
authorLink = "https://some-url"
+++

# First heading…

The front matter is the first part enclosed in +++. See zola documentation for more details.

The author and authorLink setting is optional. You can leave out the complete [extra] section. If authorLinkis defined, the author is rendered as a link to that URL. If author is missing, it defaults to "Unknown".

Elements

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.

Linking

If you want to link to an internal page, use markdown links where the path is formatted like this:

[link title](@/path/to/markdown_file.md)

Using the @/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.

{%/* infobubble(title="My Title") */%}
Your content here ….
{%/* end */%}

For a box more styled like a warning, replace info with warning.

{%/* warningbubble(title="My Title") */%}
Your content here ….
{%/* end */%}

This will render into:

{% infobubble(title="My Title") %} Your content here …. {% end %}

{% warningbubble(title="My Title") %} Your content here …. {% end %}

Summary

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.

Buttons

Styled buttons can be created using HTML inside the markdown file:

<a class="no-default button1" href="#">Click!</a>

Turns into:

Click!

Images

In image to appear on the whole page, use HTML with a figure tag:

<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:

<figure class="dark-block">
    <img src="dark-image.jpg" >
</figure>
<figure class="light-block">
    <img src="light-image.jpg" >
</figure>

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:

{{/* figure2(light="light-image.jpg", dark="dark-image.jpg") */}}

Pictures are from Unsplash.

Publish

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.