2026-10-192026-10-19

Various Markdown / HTML

Nearly all Markdown applications support the basic syntax outlined in the original Markdown design document. There are minor variations and discrepancies between Markdown processors — those are noted inline wherever possible.

Install uv

macOS and LinuxWindows

$ curl -LsSf astral.sh | sh

PS> powershell -ExecutionPolicy ByPass -c "irm astral.sh | iex"

Install Mercurial

Debian/UbuntuFedoraArch LinuxGentoomacOS (Homebrew)FreeBSDWindows (Mercurial)Windows (TortoiseHg)

apt install mercurial

dnf install mercurial

pacman -S mercurial

emerge mercurial

brew install mercurial

Binary packages can be installed using pkg:

pkg install mercurial

Alternatively, you can install from source via the ports collection:

cd /usr/ports/devel/mercurial
make install

Using the winget package manager:

winget install Mercurial.Mercurial -e

Or download from the list of binary releases.

Using the winget package manager:

winget install TortoiseHg.TortoiseHg -e

Or download from the list of binary releases.

Tip

Format and beautify markdown online for free. Fix syntax errors, standardize formatting, and lint markdown files with professional Prettier integration.
Perfect for clean, consistent markdown.

Note

Packages often have optional dependencies which are packages that provide additional functionality to the application but not strictly required for running it. When installing a package, pacman will list a package's optional dependencies, but they will not be found in pacman.log. Use the #Querying package databases command to view the optional dependencies of a package.
When installing a package which you require only as a (optional) dependency of some other package (i.e. not required by you explicitly), it is recommended to use the --asdeps option. For details, see the #Installation reason section.

Tip

When there are multiple candidates, the list of choices presented will sort first by repositories in the order they appear in pacman.conf, then alphabetically when multiple results exist from the same repository.

Warning

The Docker container is intended for local previewing purposes only and is not suitable for deployment.
This is because the web server used by MkDocs for live previews is not designed for production use and may have security vulnerabilities.

Danger

If the ESP is not mounted to /boot, make sure to not rely on the systemd automount mechanism (including that of systemd-gpt-auto-generator) during kernel upgrades. Always mount it manually prior to any system or kernel update, otherwise you may not be able to mount it after the update, locking you in the currently running kernel with no ability to update the copy of kernel on the ESP.

Alternatively preload the required kernel modules on boot, e.g.:

/etc/modules-load.d/vfat.conf

vfat
nls_cp437
nls_ascii

Note

Some text.

echo "some code"

⚠️ Warning:
Users are expected to follow the guidance in the System maintenance#Upgrading the system section to upgrade their systems regularly and not blindly run the following command.
Arch only supports full system upgrades. See System maintenance#Partial upgrades are unsupported and #Installing packages for details.

📝 Note:
Pacman will not remove configurations that the application itself creates (for example "dotfiles" in the home directory).

You can enable/start the pacman-filesdb-refresh.timer (provided within the pacman-contrib package to refresh pacman files database weekly.

Tip

If dracut works on your machine after you test it, you can uninstall | mkinitcpio. Package in extra repository on Archlinux.

📝 To generate an initramfs for the running kernel::

# dracut --add-confdir no-network /boot/initramfs-linux.img

In some cases, especially when installing a system for the first time, the above command will not work. Use the following:

$ dracut -f --regenerate-all

Note

Packages often have optional dependencies which are packages that provide additional functionality to the application but not strictly required for running it. When installing a package, pacman will list a package's optional dependencies, but they will not be found in pacman.log. Use the #Querying package databases command to view the optional dependencies of a package.
When installing a package which you require only as a (optional) dependency of some other package (i.e. not required by you explicitly), it is recommended to use the --asdeps option.
For details, see the #Installation reason section.

Tip

Warning

The Docker container is intended for local previewing purposes only and is not suitable for deployment.
This is because the web server used by MkDocs for live previews is not designed for production use and may have security vulnerabilities.

Pied Piper

The last 3 special directories.

 NB: The last 3 special directories (last, week and month) which links
 repectively to the last synced repository, to the last Monday and to the first of
 the current month.

Note

Alternatively preload the required kernel modules on boot, e.g.:

/etc/modules-load.d/vfat.conf

vfat
nls_cp437
nls_ascii

Note

alert alert-info

Several drivers has been removed from the main branch, and now live on in the Amber branch where they are community maintained and only receive critical fixes.

In order to minimize friction and maximize productivity, Material for MkDocs provides its own schema.json for mkdocs.yml. If your editor supports YAML schema validation, it's definitely recommended to set it up:

Visual Studio CodeOther

Install vscode-yaml for YAML language support.
Add the schema under the yaml.schemas key in your user or workspace settings.json:

{
  "yaml.schemas": {
    "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
  },
  "yaml.customTags": [ 
    "!ENV scalar",
    "!ENV sequence",
    "!relative scalar",
    "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
    "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
    "tag:yaml.org,2002:python/object/apply:pymdownx.superfences.fence_code_format",
    "tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping"
  ]
}

Ensure your editor of choice has support for YAML schema validation.
Add the following lines at the top of mkdocs.yml:

# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json

How to add plugins to the Docker image?

Material for MkDocs only bundles selected plugins in order to keep the size of the official image small. If the plugin you want to use is not included, you can add them easily:

Material for MkDocsInsiders

Create a Dockerfile and extend the official image:

Dockerfile

FROM squidfunk/mkdocs-material
RUN pip install mkdocs-macros-plugin
RUN pip install mkdocs-glightbox

Clone or fork the Insiders repository, and create a file called user-requirements.txt in the root of the repository. Then, add the plugins that should be installed to the file, e.g.:

user-requirements.txt

mkdocs-macros-plugin
mkdocs-glightbox

Next, build the image with the following command:

docker build -t squidfunk/mkdocs-material .

The new image will have additional packages installed and can be used exactly like the official image.

Change The Colour Palette

If you intend to change the entire colour palette of the bar, all you have to do is create a new colour palette and paste it in the config.
No need to change individual colours of all modules and sub-items.

Change The Colour Palette

If you intend to change the entire colour palette of the bar, all you have to do is create a new colour palette and paste it in the config.
No need to change individual colours of all modules and sub-items.

Note

To activate Python virtual environment on Windows Type .\venv\Scripts\activate instead.

To check Python location on Windows Typewhere python instead on the command prompt or Powershell terminal

Change the background color

To change the background color to an attention-grabbing hot pink, you might add:

config.yml

plugins:
  - social:
      cards_layout_options:
        background_color: "#ff1493"

Social cards for event pages

First, create a directory in your docs directory to hold the event pages:

Terminal

$ mkdir docs/events

Then, add a file .meta.yml inside this new directory with settings for the page icon and a hot pink background color that will stand out on social media. Note that you can override the background image by setting it to null here since it is not visible anyway because of the opaque coloring.

.meta.yml

---
icon: material/calendar-plus
social:
  cards_layout_options:
    background_image: null
    background_color: "#ff1493"
---

Now add a page within the docs/events directory. It does not need to have any special content, just a top level header.

To turn on the default/variant layout in mkdocs.yml, add the cards_layout option and also add the meta plugin:

mkdocs.yml

plugins:
  - meta
  - social:
      cards_layout: default/variant

After running mkdocs build, you can see that the social card at site/assets/images/social/events/index.png features the page icon.

Built-in plugins not working after upgrade?

Built-in plugins not working after upgrade? If one of the built-in plugins (search or tags) doesn't work anymore without any apparent error or cause, it is very likely related to custom overrides.
MkDocs 1.4.1 and above allow themes to namespace built-in plugins, which Material for MkDocs 9 now does in order to allow authors to use third-party plugins with the same name as built-in plugins.
Search your overrides for "in config.plugins" and add the material/ namespace. Affected partials:
content.html
header.html

Warning

This operation is recursive, and must be used with care since it can remove many potentially needed packages.

# pacman -Rsc package_name

Action	Command	Note
Analyzing the system state.
Show system status.	`systemctl status`	JohnAMD State: Running. Units: Loaded.
List running. units	`systemctl` or `systemctl list-units`
List failed. units	`systemctl --failed`
List installed. unit files¹.	`systemctl list-unit-files`
Show process status. for a PID	`systemctl status pid`	Cgroup slice, memory and parent

Checking the unit status.
Show a manual page Associated with a unit.	`systemctl help unit`	As supported by the unit.
Status of a unit.	`systemctl status unit`	Including whether it is running or not.
Check whether a unit is enabled.	`systemctl is-enabled unit`

Start, restart, reload unit
Start a unit immediately.	`systemctl start unit` as root
Stop a unit immediately.	`systemctl stop unit` as root
Restart a unit.	`systemctl restart unit` as root
Reload a unit and its configuration.	`systemctl reload unit` as root
Reload systemd manager configuration.²	`systemctl daemon-reload` as root	scan for new or changed units

Enabling a unit.
Enable a unit to start automatically at boot.	`systemctl enable unit` as root
Enable a unit to start automatically at boot and start it immediately.	`systemctl enable --now unit` as root
Disable a unit to no longer start at boot.	`systemctl disable unit` as root
Reenable a unit³.	`systemctl reenable unit` as root	i.e. disable and enable anew

Masking a unit.
Mask a unit to make it impossible to start⁴.	`systemctl mask unit` as root
Unmask a unit.	`systemctl unmask unit` as root	Unmask a unit to make it start

A Forest Green Background.

• For a forest green background, selecting a border color that ensures high contrast and readability in both light and dark modes is essential. In dark mode, a light gray or off-white border, such as #F0F0F0, can provide sufficient contrast against a forest green background like #3E5641, enhancing visual separation without overwhelming the design.

• This approach maintains clarity and aligns with best practices for dark mode color schemes, where subtle borders or shadows are recommended to define elements.

• In light mode, a slightly darker shade of gray or a muted neutral tone, such as #D0D0D0, works well as a border color to contrast with the forest green background while avoiding visual fatigue. This ensures that the border remains visible and functional across both modes.

• For consistency and dynamic adaptation, consider defining these colors as paired values in your design system—using a dynamic color provider that automatically adjusts the border color based on the current mode. This ensures the border remains legible and aesthetically appropriate regardless of the user’s selected theme.

For Web Development (CSS/JavaScript)⚓︎

The most robust approach uses CSS variables to define colors and a media query to switch those variables based on the user's system preference or a manual toggle.

1. Using CSS and the prefers-color-scheme media query This method respects the user's operating system setting automatically.

CSS:

CSS

• Define variables for different modes.

/* Define variables for light mode first (default) */
:root {
  --border-color: #000000; /* Black border for light mode */
  --background-color: #ffffff;
  color-scheme: light dark; /* Informs the user agent about supported schemes */
}

/* Override variables for dark mode */
@media (prefers-color-scheme: dark) {
  :root {
    --border-color: #ffffff; /* White border for dark mode */
    --background-color: #121212;
  }
}

/* Apply the variable to an element */
.my-element {
  border: 2px solid var(--border-color);
  background-color: var(--background-color);
  padding: 1rem;
}

Include the <meta name="color-scheme" content="light dark"> tag in your HTML's <head> to prevent flashes of unstyled content on page load.

2. Using the light-dark() CSS function

A newer CSS function, light-dark(), provides complete control over light and dark mode colors in one declaration. This also requires the color-scheme property to be set on the :root element.

CSS:

CSS Function

• A newer CSS function.

:root {
  color-scheme: light dark;
}

.my-element {
/* First value for light mode, second for dark mode */
  border: 2px solid light-dark(#000000, #ffffff);
}

3. Combining with JavaScript for a manual toggle

If you want to allow users to manually switch modes, use JavaScript to add a class to the <body> tag and define the dark mode styles under that class.

CSS:

CSS, manually switching modes

• Combining with JavaScript for a manual toggle.

:root {
  --border-color: #000000;
}

body.dark-mode {
  --border-color: #ffffff; /* Override the variable for manual dark mode */
}

.my-element {
  border: 2px solid var(--border-color);
}

JavaScript:

JavaScript manually switching modes

• Manually switching modes.

// Function to toggle the dark-mode class on the body
function toggleDarkMode() {
  document.body.classList.toggle('dark-mode');
}

// Example button click handler (assuming a button with id="theme-toggle")
document.getElementById('theme-toggle').addEventListener('click', toggleDarkMode);

// Optionally, detect the initial system preference
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)');
if (prefersDark.matches) {
  document.body.classList.add('dark-mode');
}

html:

HTML Source Code

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Dynamic Color Provider</title>
    <style>
        /* Define CSS variables for light mode (default) */
        :root {
            --background-color: #ffffff;
            --text-color: #000000;
            --border-color: #000000; /* Default border color */
        }

        /* Define CSS variables for dark mode */
        body.dark-mode {
            --background-color: #1a1a1a;
            --text-color: #ffffff;
            --border-color: #ffffff; /* Dark mode border color */
        }

        body {
            background-color: var(--background-color);
            color: var(--text-color);
            transition: background-color 0.3s, color 0.3s;
            font-family: sans-serif;
            display: flex;
            flex-direction: column;
            align-items: center;
            justify-content: center;
            height: 100vh;
            margin: 0;
        }

        .content-box {
            padding: 20px;
            border: 5px solid var(--border-color); /* The dynamic border */
            transition: border-color 0.3s;
            text-align: center;
        }

        button {
            margin-top: 20px;
            padding: 10px 15px;
            cursor: pointer;
        }
    </style>
</head>
<body>
    <div class="content-box">
        <h1>Dynamic Border Color</h1>
        <p>The border color of this box changes with the mode.</p>
    </div>

    <button onclick="toggleMode()">Toggle Mode</button>

    <script>
        function toggleMode() {
            const body = document.body;
            // Toggle the 'dark-mode' class on the body
            body.classList.toggle('dark-mode');
        }
    </script>
</body>
</html>

For PC's without wifi/bluetooth hardware.⚓︎

For PC's without wifi/bluetooth hardware.

The short answer is to execute the following command:

cp /usr/share/gdm/default.pa ~/.config/pulse/

So search the the global settings and find the default.pa file there. You might want to edit this file, which is what I did!

sudo nano /etc/pulse/default.pa

Comment out the lines below that loaded the bluetooth module. And the error will be removed.

### Automatically load driver modules for Bluetooth hardware (edited)
#.ifexists module-bluetooth-policy.so
#load-module module-bluetooth-policy
#.endif

#.ifexists module-bluetooth-discover.so
#load-module module-bluetooth-discover
#.endif

Or if you don't like changing a global config file as root, you can copy the file from:

/etc/pulse/default.pa

to your

~/.config/pulse/default.pa

and edit the file there and comment out these lines locally.

Tip

Please note that this applies only to systems that do not have wifi/bluetooth hardware.

Packages for common Linux and BSD distributions can be installed from the system specific repositories:

macOS & Linux:

Install uv

macOS and LinuxWindows

$ curl -LsSf astral.sh | sh

PS> powershell -ExecutionPolicy ByPass -c "irm astral.sh | iex"

The Title

The content is correctly parsed because it's separated by blank lines from the raw HTML block tags.

Installation

Use the following command to install uv:

python -m ensurepip && python -m pip install uv

Mercurial

Mercurial is available on PyPI as wheels and sdist, so one can install the latest stable version with any PyPI front-ends (like UV, pipx, pip)

Install Mercurial

Debian/UbuntuFedoraArch LinuxGentoomacOS (Homebrew)FreeBSDWindows (Mercurial)Windows (TortoiseHg)

apt install mercurial

dnf install mercurial

pacman -S mercurial

emerge mercurial

brew install mercurial

Binary packages can be installed using pkg:

pkg install mercurial

Alternatively, you can install from source via the ports collection:

cd /usr/ports/devel/mercurial
make install

Using the winget package manager:

winget install Mercurial.Mercurial -e

Or download from the list of binary releases.

Using the winget package manager:

winget install TortoiseHg.TortoiseHg -e

Or download from the list of binary releases.

Website Hex Codes.⚓︎

Website HEX codes.

I spent some time investigating and I believe any colors that follow the following HEX code will work:

• #FF0099 - 255, 0, 153 - PinkPurple
• #FF9900 - 255, 153, 0 - OrangeYellow
• #99FF00 - 153, 255, 0 - Lime Green - NOT GOOD
• #9900FF - 153, 0, 255 - PurpleViolet
• #0099FF - 0, 153, 255 - BlueCyan
• #00FF99 - 0, 255, 153 - Sea Green  - NOT GOOD

This pattern places all of these color codes on the Web Safe list of colors; I was unaware of that before I started investigating this. For a full list of all the web safe colors, check out this Web Safe Color Chart. Colour Chart and web-safe-color-chart This is the website I used to check the colors (icons, not text unfortunately) on both light and dark background: icon-set/atlas

• #FF0099 - 255, 0, 153 - PinkPurple
• #FF9900 - 255, 153, 0 - OrangeYellow
• #66CC00 - 102, 204, 0 - GreenBlue
• #9900FF - 153, 0, 255 - PurpleViolet
• #0099FF - 0, 153, 255 - BlueCyan
• #00CC66 - 0, 204, 102 - BlueGreen

Warning

Please be aware that the names I chose to describe the colours are not official names. Looking at the colours of the icons as you switch a theme from dark to light several times can create optical illusions in which the colours appear to be different on different themes

Warning

UV⚓︎

Installation⚓︎

UV Installation

Install uv with our standalone installers:

# On macOS and Linux.

curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# With pip.

$ pip install uv

# Or pipx.

$ pipx install uv

If installed via the standalone installer, uv can update itself to the latest version:

$ uv self update

Tip

• uv may also be installed with pip, Homebrew, and more. See all of the methods on the Getting-started

• See the installation documentation for details and alternative installation methods.

Documentation⚓︎

uv's documentation is available at UV Docs.

Tip

uv may also be installed with pip, Homebrew, and more. See all of the methods on the installation page

Tip

uv manages project dependencies and environments, with support for lockfiles, workspaces, and more, similar to rye or poetry.

$ uv init example Initialized project example at /home/user/example
$ cd example

$ uv add ruff
Creating virtual environment at: .venv
Resolved 2 packages in 170ms
   Built example @ file:///home/user/example
Prepared 2 packages in 627ms
Installed 2 packages in 1ms
 + example==0.1.0 (from file:///home/user/example)
 + ruff==0.5.4

$ uv run ruff check
All checks passed!

$ uv lock
Resolved 2 packages in 0.33ms
$ uv sync
Resolved 2 packages in 0.70ms
Audited 1 package in 0.02ms

Scripts⚓︎

Scripts

Create a new script and add inline metadata declaring its dependencies:

$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py

$ uv add --script example.py requests
Updated `example.py`

Note

If you are not familiar with Python environments: every Python installation has an environment that packages can be installed in. Typically, creating virtual environments is recommended to isolate packages required by each script. uv automatically manages virtual environments for you and prefers a declarative approach to dependencies.

Set up in 5 minutes

Install mkdocs-material with pip and get up
and running in minutes

Getting started
It's just Markdown

Focus on your content and generate a responsive and searchable static site

Reference
Made to measure

Change the colors, fonts, language, icons, logo and more with a few lines

Customization
Open Source, MIT

Material for MkDocs is licensed under MIT and available on GitHub

License

Tip

Add the above commands to a script and [autostart] (https://wiki.archlinux.org/title/Autostart) it to automate the process. Be sure to replace alsa_output.pci-0000_00_14.2.analog-surround-40 with the name of your sound card. Adding a delay before the script executes may also make things work smoother.

Note

The Jack/Pipewire sinks seem to change name now and then.
In the above example, alsa_output.pci-0000_00_14.2.analog-surround-40:playback_FL, sometimes changes into Built-in Audio Analog Surround 4.0:playback_FL. As a quick workaround, you could add a second set of pw-jack commands in your autostart script with the second set of names.

🖥️ Create intelligent and beautiful documentation with ease.

📝 Rich Text Formatting

Author in reStructuredText or MyST Markdown to create highly structured technical documents, including tables, highlighted code blocks, mathematical notations, and more.

🔗 Powerful Cross-Referencing

Create cross-references within your project, and even across different projects. Include references to sections, figures, tables, citations, glossaries, code objects, and more.

📚 Versatile Documentation Formats

Generate documentation in the preferred formats of your audience, including HTML, LaTeX (for PDF), ePub, Texinfo, and more.

🎨 Extensive Theme Support

Create visually appealing documentation, with a wide choice of built-in and third-party HTML themes and the ability to customize or create new themes.

🔌 Fully Extensible

Add custom functionality, via robust extension mechanisms with numerous built-in and third-party extensions available for tasks like creating diagrams, testing code, and more.

🛠️ Automatic API Documentation

Generate API documentation for Python, C++ and other software domains, manually or automatically from docstrings, ensuring your code documentation stays up-to-date with minimal effort.

🌍 Internationalization (i18n)

Add documentation translations for multiple languages to reach a global audience.

🌟 Active Community and Support

Benefit from an active community, with numerous resources, tutorials, forums, and examples.

Extension	Link	Description
cedit	CeditExtension	Command line editor for configuration files, never manually edit hgrc files again
config	ConfigExtensionCommandLine	Manage config files via command line only
configexpress	ConfigExpressExtension	Monitor and enforce client configuration from a server
dynamic_username	DynamicUsernameExtension	Set your username per directory tree.
hgcfg	HgcfgExtension	Display or modify local, user, and global configuration.
hgconfig	ConfigExtension	(dead) Manage hgrc files via dialogs and command line
path_pattern	PathPatternExtension	Define [paths] globally in your .hgrc (as patterns), and have them known all your repositories.
projrc	ProjrcExtension	Parse project specific config from .hg/projrc
rcpath	RcpathExtension	Displays Mercurial configuration file paths and names
reposettings	ReposettingsExtension	Allow repo specific configuration from central configuration files

Code Block

# code block
  print '3 backticks or'
  print 'indent 4 spaces'

Pied Piper

The last 3 special directories.

NB: The last 3 special directories (last, week and month) which links repectively to the last
synced repository, to the last Monday and to the first of the current month.

My Centered Heading

Inline code with backticks

GElectrical⚓︎

GEstimator⚓︎

Warning

In order to be able to log in, the login shell must be one of those listed in /etc/shells, otherwise the PAM module pam_shells(8) will deny the login request.

How to set up Material for MkDocs

How to set up Material for MkDocs by @james-willett – 27m – Learn how to create and host a documentation site using Material for MkDocs on GitHub Pages in a step-by-step guide.

Tip

If you don't have prior experience with Python, we recommend reading Using Python's pip to Manage Your Projects' Dependencies, which is a really good introduction on the mechanics of Python package management and helps you troubleshoot if you run into errors.

Tip

You can create a link from the user's former home directory to the new one. Doing this will allow programs to find files that have hardcoded paths.

# ln -s /my/new/home/ /my/old/home

Make sure there is no trailing / on /my/old/home.

Action	Command	Note
Analyzing the system state
Show system status	`systemctl status`
List running units	`systemctl` or `systemctl list-units`
List failed units	`systemctl --failed`
List installed unit files¹	`systemctl list-unit-files`
Show process status for a PID	`systemctl status pid`	cgroup slice, memory and parent
Checking the unit status
Show a manual page associated with a unit	`systemctl help unit`	as supported by the unit
Status of a unit	`systemctl status unit`	including whether it is running or not
Check whether a unit is enabled	`systemctl is-enabled unit`
Starting, restarting, reloading a unit
Start a unit immediately	`systemctl start unit` as root
Stop a unit immediately	`systemctl stop unit` as root
Restart a unit	`systemctl restart unit` as root
Reload a unit and its configuration	`systemctl reload unit` as root
Reload systemd manager configuration²	`systemctl daemon-reload` as root	scan for new or changed units
Enabling a unit
Enable a unit to start automatically at boot	`systemctl enable unit` as root
Enable a unit to start automatically at boot and start it immediately	`systemctl enable --now unit` as root
Disable a unit to no longer start at boot	`systemctl disable unit` as root
Reenable a unit³	`systemctl reenable unit` as root	i.e. disable and enable anew
Masking a unit
Mask a unit to make it impossible to start⁴	`systemctl mask unit` as root
Unmask a unit	`systemctl unmask unit` as root

Install Mercurial

Debian/UbuntuFedoraArch LinuxGentoomacOS (Homebrew)FreeBSDWindows (Mercurial)Windows (TortoiseHg)

apt install mercurial

dnf install mercurial

pacman -S mercurial

emerge mercurial

brew install mercurial

Binary packages can be installed using pkg:

pkg install mercurial

Alternatively, you can install from source via the ports collection:

cd /usr/ports/devel/mercurial
make install

Using the winget package manager:

winget install Mercurial.Mercurial -e

Or download from the list of binary releases.

Using the winget package manager:

winget install TortoiseHg.TortoiseHg -e

Or download from the list of binary releases.

How to add plugins to the Docker image?

Material for MkDocs only bundles selected plugins to keep the size of the official image small. If the plugin you want to use is not included, you can add them easily:

Material for MkDocsInsiders

Create a Dockerfile and extend the official image:

Dockerfile

FROM squidfunk/mkdocs-material
RUN pip install mkdocs-macros-plugin
RUN pip install mkdocs-glightbox

Clone or fork the Insiders repository, and create a file called user-requirements.txt in the root of the repository. Then, add the plugins that should be installed to the file, e.g.:

user-requirements.txt

mkdocs-macros-plugin
mkdocs-glightbox

Next, build the image with the following command:

docker build -t squidfunk/mkdocs-material .

The new image will have additional packages installed and can be used exactly like the official image.

Brief Installation Guide for `gnome-user-share`.⚓︎

Arch Linux gnome-user-share

To usegnome-user-shareon Arch Linux for user-level file sharing within GNOME, you need to ensure the necessary components are installed and configured.
Thegnome-user-sharepackage provides an easy way to share folders through GNOME, typically usingSambafor network sharing.
It is part of the GNOME desktop environment and is designed to integrate with Nautilus (GNOME's file manager) to allow users to share folders via a simple right-click option in the file manager's properties.

Installation and Configuration Steps:⚓︎

Install the necessary packages: Open a terminal and use pacman to install thegnome-user-share,apache, andnss-mdns packages.nss-mdnsis needed for Avahi hostname resolution.

1. Install the gnome-user-share package using pacman.

# sudo pacman -S gnome-user-share apache nss-mdns

For file sharing to work properly over the local network, ensure that the mDNS service is correctly configured.
Whilesystemd-resolvedprovides basicmDNSfunctionality, it may not support all required features.
The Arch Wiki recommends usingavahi-daemonfor fullmDNS (Multicast DNS Protocol)support, which is necessary for the sharing feature to be discoverable on the network.

Avahi Service

2. To enable this, install and start theavahiservice:

# sudo pacman -S avahi
# sudo systemctl enable avahi-daemon
# sudo systemctl start avahi-daemon

Configure Avahi for hostname resolution: Edit the hosts line in /etc/nsswitch.confto include mdns_minimal and [NOTFOUND=return] so thatmDNShostnames are resolved correctly. The line should look like this:

Tip

3. Configure Avahi for Hostname Resolution.

# hosts: mymachines resolve [!UNAVAIL=return] files myhostname dns hosts: mymachines mdns_minimal [NOTFOUND=return] resolve [!UNAVAIL=return] files myhostname dns

Installgvfs-smb(Optional for Windows Interoperability): If you also want to browse and access Samba shares from your Arch Linux system (In other words, not host thegnome-user-share viaSamba), installgvfs-smb.

Tip

4. After installation, you may need to enable and start theavahi daemonfor zero-configuration networking, which helps in discovering shared folders on the local network:

# sudo systemctl enable avahi-daemon
# sudo systemctl start avahi-daemon

Final Configuration

5. Enable Sharing in GNOME Settings:

 1. Open the Activities overview and search for Settings.
 2. Navigate to the Sharing panel.
 3. Toggle the main Sharing switch to On.
 4. Select Personal File Sharing and switch it to On.
 5. This makes your ~/Public folder accessible on the local network.
 6. A URI will be displayed that other users can use to access your shared folder.

Warning

NB - Do not proceed without reading this.
Note that gnome-user-share has been deprecated and marked as broken since June 30, 2025, due to unresolved build issues, including the missing libnautilus-extension dependency.
As a result, the package is no longer recommended for use in new installations. Users are encouraged to consider alternative file-sharing solutions such as Samba for more reliable and supported network sharing.

Warning

From a configuration point of view, those are not equivalent to setting a compound "default" PCM device, since most users specify addressing type in there also, which actually may be the same, but the assignment itself still differs.
Also, defaults.pcm.card is referred to multiple times in ALSA configuration files, usually as a fallback assignment, where different environment variables take precedence.

Misc

Import the main components:

1. From src.example import Calculator
2. From src.example.utils import validate_input, format_number

Validate inputs and perform calculation:

1. a = validate_input("10.5")
2. b = validate_input("5.2")
3. result = calc.add(a, b)

Format output:

1. print(format_number(result))  # Output: 15.70

In order to minimize friction and maximize productivity, Material for MkDocs provides its own schema.json for mkdocs.yml. If your editor supports YAML schema validation, it's definitely recommended to set it up:

Visual Studio CodeOther

Install vscode-yaml for YAML language support.

Add the schema under the yaml.schemas key in your user or workspace settings.json:

{
  "yaml.schemas": {
    "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
  },
  "yaml.customTags": [
    "!ENV scalar",
    "!ENV sequence",
    "!relative scalar",
    "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
    "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
    "tag:yaml.org,2002:python/object/apply:pymdownx.superfences.fence_code_format",
    "tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping"
  ]
}

Ensure your editor of choice has support for YAML schema validation.

Add the following lines at the top of mkdocs.yml:

# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json

BashZshfishElvishPowerShell / pwsh

echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

echo 'uv generate-shell-completion fish | source' > ~/.config/fish/completions/uv.fish

echo 'eval (uv generate-shell-completion elvish | slurp)' >> ~/.elvish/rc.elv

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'

Install Piers-Linux

Material for MkDocs only bundles selected plugins to keep the size of the official image small. If the plugin you want to use is not included, you can add them easily:

CPU & MemoryMemory StatusMercurialTasksUnknownFreeBSD / ArchWindows (Network)Windows (Linux Pkgs)

$ Requires Delegation: CPUAccounting, CPUWeight, CPUQuota, AllowedCPUs, AllowedMemoryNodes

$ Yes: MemoryLow, MemoryHigh, MemoryMax, MemorySwapMaxl

$ pacman -S mercurial

$ Yes: TasksMax

$ No: ?

Binary packages can be installed using pkg:

$ sudo pacman -S piers-linux

Alternatively, install from yay:

$ cd /usr/home/piers-linux
$ make install

Using the winget package manager:

PS> No: IPAddressDeny, DeviceAllow, DevicePolicy

Or download from the list of binary releases.

Using the winget package manager:

PS> Yes: Packages for common Linux

Or download from the list of binary releases.

Alignment	Environment	Command
Left justified	`flushleft`	`\raggedright`
Right justified	`flushright`	`\raggedleft`
Center	`center`	`\centering`

Metadata syntax	Start date	End date	ID
`<taskID>, <startDate>, <endDate>`	`startdate` as interpreted using `dateformat`	`endDate` as interpreted using `dateformat`	`Piers`
`<taskID>, <startDate>, <length>`	`startdate` as interpreted using `dateformat`	Start date + `length`	`taskID`
`<taskID>, after <otherTaskId>, <endDate>`	End date of previously specified task `otherTaskID`	`endDate` as interpreted using `dateformat`	`taskID`
`<taskID>, after <otherTaskId>, <length>`	End date of previously specified task `otherTaskID`	Start date + `length`	`taskID`
`<taskID>, <startDate>, until <otherTaskId>`	`startdate` as interpreted using `dateformat`	Start date of previously specified task `otherTaskID`	`taskID`
`<taskID>, after <otherTaskId>, until <otherTaskId>`	End date of previously specified task `otherTaskID`	Start date of previously specified task `otherTaskID`	`taskID`
`<startDate>, <endDate>`	`startdate` as interpreted using `dateformat`	`enddate` as interpreted using `dateformat`	n/a
`<startDate>, <length>`	`startdate` as interpreted using `dateformat`	Start date + `length`	n/a
`after <otherTaskID>, <endDate>`	End date of previously specified task `otherTaskID`	`enddate` as interpreted using `dateformat`	n/a
`after <otherTaskID>, <length>`	End date of previously specified task `otherTaskID`	Start date + `length`	n/a
`<startDate>, until <otherTaskId>`	`startdate` as interpreted using `dateformat`	Start date of previously specified task `otherTaskID`	n/a
`after <otherTaskId>, until <otherTaskId>`	End date of previously specified task `otherTaskID`	Start date of previously specified task `otherTaskID`	n/a
`<endDate>`	End date of preceding task	`enddate` as interpreted using `dateformat`	n/a
`<length>`	End date of preceding task	Start date + `length`	n/a
`until <otherTaskId>`	End date of preceding task	Start date of previously specified task `otherTaskID`	n/a

Method	Description
`GET`	Fetch resource
`PUT`	Update resource
`DELETE`	Delete resource

Method	Description
`GET`	Fetch resource
`PUT`	Update resource
`DELETE`	Delete resource

Material for MkDocs	Before	Now	Relative
Index size	573 kB	335 kB	–42%
Index size (`gzip`)	105 kB	78 kB	–27%
Indexing time	265 ms	177 ms	–34%
KJV Markdown	Before	Now	Relative
Index size	8.2 MB	4.4 MB	–47%
Index size (`gzip`)	2.3 MB	1.2 MB	–48%
Indexing time	2,700 ms	1,390 ms	–48%

Failure

The last 3 special directories.

NB: The last 3 special directories (last, week and month) which links repectively to the last
synced repository, to the last Monday and to the first of the current month.

Bug

The last 3 special directories.

NB: The last 3 special directories (last, week and month) which links repectively to the last
synced repository, to the last Monday and to the first of the current month.

→ xiph.org

I DON'T BELIEVE YOU! This article from the guys at xiph.org, (The people who brought you FLAC and Ogg Vorbis) who explain it better than I can at xiph.org

NB: The last 3 special directories

NB: The last 3 special directories (last, week and month) which links repectively to the last synced repository, to the last Monday and to the first of the current month.

Example

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Inner Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Sublime Text Cheatsheet⚓︎

Select & Expand⚓︎

Shortcut	Action
`⌘ D`	select current word (repeat to include next instance of word)
`⌘ L`	select current line (repeat to include next line)
`⌘ ⇧ L`	split selection into multiple lines
`⌘ ⇧ A`	select text inside tag (repeat to expand)
`Ctrl ⇧ M`	select to curly or angle brackets (repeat to expand)

Replace ⌘ with Ctrl on Windows and Linux.

Code Folding⚓︎

Shortcut	Action
`⌘ Alt [`	fold closest block
`⌘ Alt ]`	unfold closest block
`⌘ K` `⌘ 1`	fold all first level code blocks
`⌘ K` `⌘ 2`	fold all second level code blocks
`⌘ K` `⌘ 3 (etc)`	fold all third level code blocks (etc)
`⌘ K` `⌘ T`	fold all HTML attributes
`⌘ K` `⌘ 0`	unfold everything

Editing⚓︎

Shortcut	Action
`⌘ ⇧ D`	duplicate current line/selection
`⌘ ⇧ K`	delete current line/selection
`⇧ del`	delete current line/selection
`⌘ ⇧ ↑`	move line up
`⌘ ⇧ ↓`	move line down

Goto⚓︎

Shortcut	Action
`⌘ P`	goto anything
`⌘ G`	goto line number
`⌘ R`	goto symbol
`⌘ P, :`	goto line number (enter number after `:`)
`⌘ P, #`	goto and list fuzzy-matches of string (enter characters after `#`)
`⌘ P, @`	goto and list symbol (begin typing symbol name after `@`)

Command line⚓︎

$ subl .
$ subl README.md

Use subl to open files in Sublime from the terminal.

Expression	Example	Description
`!!`	`sudo !!`	Last cmd (`sudo !!`)
`!*`	`vim !*`	Last cmd's params (`vim !*`)
`!^`		Last cmd's first param
`!$`		Last cmd's last param
`!?ls` `<tab>`	`sudo !?mv` `<tab>`	cmd & params of last `ls` cmd
`!?ls?:*` `<tab>`		Params of last `ls` cmd
`*(m0)`	`rm *(m0)`	Last modified today
`*(m-4)`		Last modified <4 days ago

Process Substitution⚓︎

Expression	Example	Description
`<(COMMAND)`	`grep "needle" <(curl "https://haystack.io")`	Replace argument with named pipe/FIFO (read-only) with command output
`=(COMMAND)`	`vim =(curl "https://haystack.io")`	Replace argument with file (writable) containing command output

Expression	Example	Description
`<(COMMAND)`	`grep "needle" <(curl "https://haystack.io")`	Replace arg. with named pipe/FIFO (RO) with cmd output
`=(COMMAND)`	`vim =(curl "https://haystack.io")`	Replace arg. with file (wrt) containing cmd output

Einstein Field Equations (Foundation)

$R_{\mu\nu} - \frac{1}{2}g_{\mu\nu}R + \Lambda g_{\mu\nu} = \frac{8\pi G}{c^4}T_{\mu\nu}$

Fixing Incorrect Printing and Erroneous ToC Entries

(1.) Use the correct CSS class:

Instead of .unlisted (which requires that extra config), use the class .skip-toc or simply { data-toc-label="" }. However, the most reliable "MkDocs-Material" way to hide a heading from the ToC while keeping it on the page is:

Option A: (Best for MkDocs-Material):

#### Documentation for `MyClass` { #doc-myclass data-toc-label="" }

Setting data-toc-label to an empty string effectively removes it from the sidebar in most Material setups.

Option B: (The "Hidden" Heading trick):

If Option A still shows a blank bullet point in the ToC, use this syntax which uses the attr_list to tell the TOC extension specifically to ignore it:

#### Documentation for `MyClass` {: .ignore-toc }

Note: This only works if we can tell the TOC to ignore that class, but since your TOC config is being picky, let's try the direct approach below.

(2.) The "No-Fail" Approach:

If you want to guarantee it never hits the ToC and never crashes your server, stop using the #### Markdown syntax for the Result tab only, and use plain HTML. MkDocs' TOC extension ignores raw HTML tags:

=== "Result"
<h4 style="font-weight: bold; margin-top: 1em;">Documentation for <code>MyClass</code></h4>
Print print print!

<h4 style="font-weight: bold; margin-top: 1em;"><code>method_a(self)</code></h4>
Print A!

Fixing Incorrect Printing and Erroneous TOC Entries

1. Use the correct CSS class:

Instead of .unlisted (Requires that extra config), use the class .skip-toc or simply { data-toc-label="" }.
However, the most reliable "MkDocs-Material" way to hide a heading from the ToC while keeping it on the page is:

Option A: (Best for MkDocs-Material):

#### Documentation for `MyClass` { #doc-myclass data-toc-label="" }

Setting data-toc-label to an empty string effectively removes it from the sidebar in most Material setups.

Option B: (The "Hidden" Heading trick):

If Option A still shows a blank bullet point in the ToC, use this syntax which uses the attr_list to tell the TOC extension specifically to ignore it:

#### Documentation for `MyClass` {: .ignore-toc }

Note: This only works if we can tell the TOC to ignore that class, but since your TOC config is being picky, let's try the direct approach below.

2. The "No-Fail" Approach:

If you want to guarantee it never hits the ToC and never crashes your server, stop using the #### Markdown syntax for the Result tab only, and use plain HTML. MkDocs' TOC extension ignores raw HTML tags:

=== "Result"
<h4 style="font-weight: bold; margin-top: 1em;">Documentation for <code>MyClass</code></h4>
Print print print!

<h4 style="font-weight: bold; margin-top: 1em;"><code>method_a(self)</code></h4>
Print A!

Useful Links⚓︎

Installation Guide
View Guide

Step-by-step instructions to get MkDocs up and running.
Configuration (docs_dir)
View Config

Learn how to set up your source directory structure.
Deploying Your Docs
View Guide

How to publish your documentation to the web.
Documentation Layout
View Layout

Configure the navigation and global site structure.
GitHub Discussions
Join Discussions

Ask questions and engage with the community.
GitHub Issues
View Issues

Report bugs or request new features.
Site Name
View Settings

Define the title of your project and browser tab.
Theme
View Theme

Customise the look and feel of your documentation.
User Guide
Open Guide

The complete manual for all MkDocs features.

Installation Guide
View Guide

Step-by-step instructions to get MkDocs up and running.
Configuration (docs_dir)
View Config

Learn how to set up your source directory structure.
Deploying Your Docs
View Guide

How to publish your documentation to the web.
Documentation Layout
View Layout

Configure the navigation and global site structure.
GitHub Discussions
Join Discussions

Ask questions and engage with the community.
GitHub Issues
View Issues

Report bugs or request new features.
Site Name
View Settings

Define the title of your project and browser tab.
Theme
View Theme

Customise the look and feel of your documentation.
User Guide
Open Guide

The complete manual for all MkDocs features.

Second Law of Thermodynamics

The mathematical expression of the Second Law of Thermodynamics is often presented in terms of the change in entropy ($\Delta S$) for an isolated system or the universe.
Here are examples of the MathJax code for common formulations of the Second Law: General Statement (Entropy of the Universe) The most common and general mathematical statement is that the total entropy of an isolated system (the universe) can never decrease.

MathJax Code (inline):

Renders as: $\Delta S_{\text{univ}} \ge 0$

\[\Delta S_{\text{total}} = \Delta S_{\text{sys}} + \Delta S_{\text{surr}} \geq 0\]

For a System and its Surroundings:

The total entropy change is the sum of the changes in the system and the surroundings, which must be greater than or equal to zero.

MathJax Code (display mode):

Renders as: $\Delta S_{\text{total}} = \Delta S_{\text{sys}} + \Delta S_{\text{surr}} \geq 0$

For any process, the change in entropy of a system is greater than or equal to the heat transfer ($Q$) divided by the absolute temperature ($T$). The equality holds for reversible processes, and the inequality for irreversible (real spontaneous) processes.

MathJax Code (inline)

Renders as: $dS \ge \frac{\delta Q}{T}$

Practical Diagrams⚓︎

Practical Diagrams

There are a few diagrams that we feel do not work well for us, and we thought it useful to share why. The main reason is that a few of the diagrams are a bit impractical to use due to sizing and scaling issues. While there may be a way to massage them to work, we have not currently invested any time in workarounds for these diagrams.
Some of the less practical examples may work better if they were pre-rendered and included as an image instead. This seems to be what Mermaid does in their own documents.

Flowcharts

graph TD
    A[Hard] -->|Text| B(Round)
    B --> C{Decision}
    C -->|One| D[Result 1]
    C -->|Two| E[Result 2]

Sequence Diagrams

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!

Class Diagrams

classDiagram
    Class01 <|-- AveryLongClass : Cool
    Class03 *-- Class04
    Class05 o-- Class06
    Class07 .. Class08
    Class09 --> C2 : Where am i?
    Class09 --* C3
    Class09 --|> Class07
    Class07 : equals()
    Class07 : Object[] elementData
    Class01 : size()
    Class01 : int chimp
    Class01 : int gorilla
    Class08 <--> C2: Cool label

Entity Relationships

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

State Diagrams

stateDiagram
    [*] --> First
    First --> Second
    First --> Third

    state First {
        [*] --> fir
        fir --> [*]
    }
    state Second {
        [*] --> sec
        sec --> [*]
    }
    state Third {
        [*] --> thi
        thi --> [*]
    }

Pie

pie
    title Key elements in Product X
    "Calcium" : 42.96
    "Potassium" : 50.05
    "Magnesium" : 10.01
    "Iron" :  5

Click to see Code

``` py linenums="1"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Table Reference: systemctl⚓︎

Action	Command	Note
Analyzing the system state
Show system status	`systemctl status`
List running units	`systemctl` or `systemctl list-units`
List failed units	`systemctl --failed`
List installed unit files¹	`systemctl list-unit-files`
Show process status for a PID	`systemctl status pid`	cgroup slice, memory and parent
Checking the unit status
Show a manual page associated with a unit	`systemctl help unit`	as supported by the unit
Status of a unit	`systemctl status unit`	including whether it is running or not
Check whether a unit is enabled	`systemctl is-enabled unit`
Starting, restarting, reloading a unit
Start a unit immediately	`systemctl start unit` as root
Stop a unit immediately	`systemctl stop unit` as root
Restart a unit	`systemctl restart unit` as root
Reload a unit and its configuration	`systemctl reload unit` as root
Reload systemd manager configuration²	`systemctl daemon-reload` as root	scan for new or changed units
Enabling a unit
Enable a unit to start automatically at boot	`systemctl enable unit` as root
Enable a unit to start automatically at boot and start it immediately	`systemctl enable --now unit` as root
Disable a unit to no longer start at boot	`systemctl disable unit` as root
Reenable a unit³	`systemctl reenable unit` as root	i.e. disable and enable anew
Masking a unit
Mask a unit to make it impossible to start⁴	`systemctl mask unit` as root
Unmask a unit	`systemctl unmask unit` as root

Lists every unit file installed on disk with its enabled state, including units that are not currently loaded. systemctl list-units only shows units that are loaded in memory. ↩
Run this after creating or editing unit files or drop-ins so systemd re-reads them. It does not restart services that are already running. ↩
Equivalent to a disable followed by an enable. It recreates the unit's symlinks from its current [Install] section, which is useful after that section has changed. ↩
Masking links the unit to /dev/null, so it cannot be started manually or pulled in as a dependency. This is stronger than disabling, and unmask reverses it. ↩

Various Markdown / HTML

alert alert-info

For Web Development (CSS/JavaScript)⚓︎

For PC's without wifi/bluetooth hardware.⚓︎

Packages for common Linux and BSD distributions can be installed from the system specific repositories:

macOS & Linux:

Mercurial

Website Hex Codes.⚓︎

UV⚓︎

Installation⚓︎

Documentation⚓︎

Scripts⚓︎

GElectrical⚓︎

GEstimator⚓︎

Brief Installation Guide for gnome-user-share.⚓︎

Installation and Configuration Steps:⚓︎

Sublime Text Cheatsheet⚓︎

Select & Expand⚓︎

Code Folding⚓︎

Editing⚓︎

Goto⚓︎

Command line⚓︎

Process Substitution⚓︎

Useful Links⚓︎

Practical Diagrams⚓︎

Table Reference: systemctl⚓︎

Brief Installation Guide for `gnome-user-share`.⚓︎