Skip to content

Website

The website, meaning everything accessible under the purrbot.site domain, is created using ProperDocs, a continuation of MkDocs, alongside a theme, plugins and extensions.

The entirety of the site is available on [Codeberg] and we welcome any contributions to help improve the site.

Prerequisites

Before contributing, it's important that you have at least basic knowledge of the following:

  • General understanding of Markdown formatting

    You know the basics of markdown formatting such as writing in bold, italic, etc.
    Knowledge of Python-Markdown and its quirks are beneficial.

  • Knowledge with ProperDocs or alternatively MkDocs

    ProperDocs is pretty much the same as MkDocs in terms of functionality, just with bug fixes and updated dependencies.
    Important is to note that you need to use properdocs instead of mkdocs in the command-line.

  • Knowledge of configuring and using Plugins and Extensions

    The Website takes heavy use of the various plugins and extensions available, to provide the docs it does.

Important notes

Please read the following points regarding this site to understand how it works and what to keep in mind.

Admonitions, Details and Tabs

This website uses the extensions pymdownx.blocks.admonition, pymdownx.blocks.details and pymdownx.blocks.tab to provide Admonition, Details and Tabs support respectively.

They replace the admonition, pymdownx.details and pymdownx.tabbed extensions respectively.
Visually is there no differences to the original, but syntax-wise are all using the same core format:

/// <type> | <title>
content
///

Some points worth noting:

  • For admonitions in this Website should you always use the Type name defined in the types option of the extension.
  • Always define the type for a Details block, even if it is the default.
  • Options are always at the top, need 4 spaces before them and need an empty line before the content. This is required by the blocks extension.

Nested Blocks

Given all blocks use the same syntax, nesting becomes a bit more involved.

To nest a block inside another block, increase either block's number of forward slashes (/):

<!-- Either works -->

/// info
//// warning
Nested warning
////
///

//// info
/// warning
Nested warning
///
////

Info

Warning

Nested warning

For the website are we using larger numbers for nested entries (The first example), which you also should use.

We use the Privacy Plugin of MaterialX to automatically apply specific attributes to Links that lead away from the main purrbot.site domain.
More specifically, every link has a target="_blank" and rel="nofollow noopener"attribute applied to open it in a new tab and increase privacy by preventing link-following.

Commonly used links, such as linking to the Discord server or the repositories, should be put in the links.md file found in the snippets folder of the repository. This file contains all the links commonly used within this website, formatted as reference links and injected into the markdown using the pymdownx.snippets extension.

Should you add a new link that is used across multiple locations in the site, make sure to add it to the links.md file and use it either through [name] or [text][name] where name would be the reference you defined in the file.