Getting started with a Markdown site

This is the richer site path: Everlock renders the repository into a documentation-style site on request.

1. Enable the required backends

/backends enable site-http git-ssh

Reconnect after restart if needed.

Expected result:

  enabled: site-http, git-ssh
  restart required

2. Create the site

/site create my-docs vhost=localhost mode=markdown

Expected output shape:

  Site 'my-docs' created (store: my-docs, auth: public).
  Granted admin write access to push content: */git/my-docs

3. Clone the store

git clone ssh://admin@localhost:2222/my-docs
cd my-docs

4. Add a minimal Markdown site

Create site.toml:

title = "My Docs"
description = "Published through Everlock"
timezone = "Europe/Berlin"

[nav]
links = [
  { label = "Home", url = "/" },
  { label = "Docs", url = "/docs/" },
]

Create index.md:

---
title: Home
---

# My Docs

Welcome to my Everlock-powered documentation site.

5. Commit and push

git add .
git commit -m "initial Markdown site"
git push

Expected result:

the Markdown files become live immediately after the push
Everlock renders them on request through the site backend

What Markdown mode gives you

Markdown page rendering
section pages and generated lists
frontmatter
site.toml navigation and metadata
timezone-aware template date helpers
custom layouts
shortcodes
automatic heading anchors for in-page links
feeds and sitemap
generated search index
taxonomies

Heading anchors

Every heading is given an id automatically, so you can deep-link to any section and in-page links resolve. The id is the heading text lowercased, with spaces turned into hyphens and punctuation dropped — so ## Create the socket units becomes #create-the-socket-units, and ## systemd service (recommended) becomes #systemd-service-recommended.

Link to a section with a normal Markdown link, on the same page or another:

See [the socket units](#create-the-socket-units) below.
See [deployment](/docs/deployment#systemd-service-recommended).

Anchors are always generated, independent of any [markdown] rendering options.

When to use this mode

Choose markdown when:

you want a docs-first public site
you want content to stay readable in the repository
you want Everlock itself to be the site engine instead of a separate build step