Skip to content

Markdown

LevantGit uses MarkDown structured text in many places, you can recognise it by the .md file extension. Markdown is plain text format for writing structured documents, allowing one to write "plain" text files that nonetheless have "fancy" formatting, while still keeping the plain-text version readable.

Unfortunately, due to historical implementation differences, many subtle dialects exist. To avoid adding to the confusion, LevantGit tries to follow "GitHub Flavoured Markdown (GFM)" as close as possible. "GFM" is an extension on top of the rigorously-specified CommonMark standard. CommonMark flavours are used by most major web platforms (e.g. Reddit, Stack Overflow, Discourse) and git forges (GitHub, GitLab and our very own LevantGit), thus you shouldn't run into any surprises with LevantGit.

For a quick introduction to the syntax and features of GitHub Flavoured Markdown, see the GitHub documentation: - Basic formatting - Advanced formatting

For a deeper history about CommonMark, its spec, and its reason for existence, see CommonMark.org.

Rendering options

Some LevantGit's markdown rendering behaviors can be fine-tuned by global config options, see the [markdown] config section in the app.example.ini

When rendering links for <a href>, <img src> and <video src>, LevantGit resolves the link paths in the rendering context.

  • If the link is an absolute path with scheme, the link is kept as-is.
  • If the link is an URL path, it is resolved with the base path of current rendering context.
  • In a comment-like context (issues, pull-requests, commit message), the base path is current repository's home link: /owner-name/repo-name.
  • In a repository file context (markdown files in the repository), the base path is current git ref path.

To make users easier to resolve a link to the LevantGit instance's root path, LevantGit has a special /:root path syntax. This will always resolve to LevantGit's ROOT_URL.

LevantGit also supports GitHub's ?raw=1 query parameter. A request to /owner-name/repo-name/src/branch/main/file?raw=1 will be redirected to /owner-name/repo-name/raw/branch/main/file. This makes it possible to target raw contents from relative links (normally, the src/ section of the path is provided automatically by LevantGit and cannot be overriden).

For example, when rendering a markdown file in /owner-name/repo-name/src/branch/main/dir: 1) Absolute with scheme: Link https://example.org will be rendered as-is. 2) Relative from current file: Link sub/fileis resolved to /owner-name/repo-name/src/branch/main/dir/sub/file 3) Relative from repo root: Link /sub/file (note leading slash) is resolved to /owner-name/repo-name/src/branch/main/sub/file 4) Raw media: If the link is used as src of an image or video, then it is resolved to /owner-name/repo-name/raw/... 5) Raw relative: sub/file?raw=1 will resolve to /owner-name/repo-name/src/branch/main/dir/sub/file?raw=1, which will redirect to /owner-name/repo-name/raw/branch/main/dir/sub/file. 6) explicit root: Link /:root/any-path is always resolved to $ROOT_URL/any-path without any further processing.

Issue and pull-request reference

Using issue/pull-request numbers in a list:

* #123
* #456

It will be rendered with issue titles to:

* the issue title (#123)
* the other issue title (#456)

Math expressions

LevantGit supports GitHub-like math expression formatting.

Inline expression

  • $\alpha$: quoted by single-dollar $
  • $$\alpha$$: quoted by double-dollar $$
  • $`\alpha`$: quoted by dollar with backquotes, the backquotes could repeat like normal code blocks.

Block expression

Using $$:

$$
\alpha
$$

Using code-block with language:

```math
\alpha
```

Frontmatter

LevantGit supports frontmatter and Table of Contents (TOC) rendering. By default, frontmatter rendering is enabled, and TOC rendering is disabled.

Enabling TOC rendering

To enable TOC rendering for a markdown file, add include_toc: true to its frontmatter section.

Disabling frontmatter

To disable frontmatter rendering for a markdown file, add LevantGit: none to its frontmatter section.

Example

---
include_toc: true
LevantGit: none
---

Then, when you preview this markdown file in LevantGit, the frontmatter section will not be rendered, and a Table of Contents will be generated at the top of the content.