ProperDocs

https://properdocs.org/
Admin
ProperDocs is a fast, simple, and gorgeous static site generator for building project documentation...
Tokens:38,907
Snippets:608
Trust Score:4.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Pip using get-pip.py

Source: https://properdocs.org/user-guide/installation

Install pip for the first time by downloading and running the get-pip.py script. This is useful if pip is not already installed.

```bash
python get-pip.py
```

--------------------------------

### Install ProperDocs and Theme

Source: https://properdocs.org/getting-started

Installs ProperDocs and a basic theme from the command line. Ensure you have Python and pip installed.

```bash
pip install properdocs properdocs-theme-mkdocs
```

--------------------------------

### ProperDocs Version Output Example

Source: https://properdocs.org/about/release-notes

Example output when checking the ProperDocs version. This indicates the installed version and its location.

```text
$ properdocs --version
properdocs, version 1.6.7 from /path/to/properdocs (Python 3.13)
```

--------------------------------

### Install Documentation Dependencies (Exact Versions)

Source: https://properdocs.org/about/contributing

Install exact versions of dependencies for documentation development into a virtual environment using a requirements file.

```bash
.venv/bin/pip install -r requirements/requirements-docs.txt
```

--------------------------------

### Install Documentation Dependencies (Latest Versions)

Source: https://properdocs.org/about/contributing

Install the latest versions of all dependencies for documentation development into a virtual environment using a dynamic requirements source.

```bash
.venv/bin/pip install -r $(properdocs get-deps)
```

--------------------------------

### Install a ProperDocs Plugin

Source: https://properdocs.org/dev-guide/plugins

Use pip to install third-party ProperDocs plugins. Ensure you exercise caution as this installs and executes Python code.

```bash
pip install properdocs-foo-plugin
```

--------------------------------

### Install ProperDocs on Windows using py launcher

Source: https://properdocs.org/user-guide/installation

Alternative command for installing ProperDocs on Windows using the 'py -m' prefix, which can resolve PATH issues.

```bash
py -m pip install properdocs
```

--------------------------------

### Register Plugin via Setuptools Entry Points

Source: https://properdocs.org/dev-guide/plugins

Define plugin registration in your `setup.py` using setuptools' `entry_points` under the `properdocs.plugins` key. This makes your plugin discoverable by ProperDocs when installed.

```python
entry_points={
    'properdocs.plugins': [
        'pluginname = path.to.some_plugin:SomePluginClass',
    ]
}
```

--------------------------------

### Install Read the Docs Theme

Source: https://properdocs.org/user-guide/choosing-your-theme

Install the Read the Docs theme using pip. This theme is a clone of the default theme used by the Read the Docs service.

```bash
pip install properdocs-theme-readthedocs
```

--------------------------------

### Serve ProperDocs Project Locally

Source: https://properdocs.org/getting-started

Starts the ProperDocs development server to preview your documentation locally. The server watches for changes and auto-reloads the browser.

```bash
$ properdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.22 seconds
INFO    -  [15:50:43] Watching paths for changes: 'docs', 'properdocs.yml'
INFO    -  [15:50:43] Serving on http://127.0.0.1:8000/
```

--------------------------------

### Configure Theme with String Name

Source: https://properdocs.org/user-guide/configuration

Sets the theme by its string name. Ensure the theme is installed.

```yaml
theme: mkdocs
```

--------------------------------

### Run the ProperDocs development server

Source: https://properdocs.org/user-guide/cli

Starts a local development server to preview your documentation. Options control the development address, browser opening, live reloading, and build behavior.

```bash
properdocs serve [OPTIONS]
```

--------------------------------

### Install ProperDocs with i18n Support

Source: https://properdocs.org/user-guide/localizing-your-theme

Install ProperDocs with internationalization support to enable theme localization. This is a prerequisite for theme localization to function correctly.

```bash
pip install 'properdocs[i18n]'
```

--------------------------------

### Verify ProperDocs Installation

Source: https://properdocs.org/user-guide/installation

Check that the ProperDocs command-line tool is installed correctly and display its version.

```bash
$ properdocs --version
properdocs, version 1.2.0 from /usr/local/lib/python3.8/site-packages/properdocs (Python 3.8)
```

--------------------------------

### Install ProperDocs using Pip

Source: https://properdocs.org/user-guide/installation

Install the ProperDocs package using pip. This command makes the 'properdocs' command-line tool available.

```bash
pip install properdocs
```

--------------------------------

### Install Latest Development Version

Source: https://properdocs.org/about/contributing

Install the latest development version of ProperDocs using pip. Recommended to use within a virtual environment.

```bash
pip install git+https://github.com/properdocs/properdocs.git
```

--------------------------------

### Check ProperDocs Version

Source: https://properdocs.org/about/release-notes

Verify your currently installed ProperDocs version using this command. It shows the version number and installation path.

```bash
properdocs --version
```

--------------------------------

### Install MkDocs with i18n support

Source: https://properdocs.org/about/release-notes

Install the necessary dependencies to enable language localization for MkDocs themes. This command is required before translations will function.

```bash
pip install 'mkdocs[i18n]'
```

--------------------------------

### Multi-Page Project File Layout

Source: https://properdocs.org/user-guide/writing-your-docs

An example of a project structure with multiple Markdown files for different pages.

```yaml
properdocs.yml
docs/
    index.md
    about.md
    license.md
```

--------------------------------

### Theme Configuration Example (mkdocs_theme.yml)

Source: https://properdocs.org/dev-guide/themes

The mkdocs_theme.yml file in your theme's root directory defines default configuration options. These options can be overridden by the user in their properdocs.yml.

```yaml
show_sidebar: true
```

--------------------------------

### Check Python and Pip Versions

Source: https://properdocs.org/user-guide/installation

Verify if Python and pip are installed and check their versions. These are required for ProperDocs installation.

```bash
$ python --version
Python 3.8.2
```

```bash
$ pip --version
pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8)
```

--------------------------------

### on_startup Event

Source: https://properdocs.org/dev-guide/plugins

The `on_startup` event runs once at the very beginning of a `properdocs` invocation. It's useful for initial setup, though `__init__` is preferred for general initialization and `on_config` for per-build variables.

```APIDOC
## on_startup

### Description
The `startup` event runs once at the very beginning of an `properdocs` invocation.

### Parameters
- **`command`** (`Literal['build', 'gh-deploy', 'serve']`) - Description: the command that ProperDocs was invoked with, e.g. "serve" for `properdocs serve`.
- **`dirty`** (`bool`) - Description: whether `--dirty` flag was passed.
```

--------------------------------

### Configuring a List of Integers

Source: https://properdocs.org/about/release-notes

Examples demonstrating how to define a list of integers using `config_options.ListOfItems`. This includes required lists, optional lists with a default empty list, and optional lists that default to None.

```python
from mkdocs.config import config_options as c

# Required to specify
foo = c.ListOfItems(c.Type(int))
```

```python
from mkdocs.config import config_options as c

# Optional, default is []
foo = c.ListOfItems(c.Type(int), default=[])
```

```python
from mkdocs.config import config_options as c

# Optional, default is None
foo = c.Optional(c.ListOfItems(c.Type(int)))
```

--------------------------------

### ProperDocs Get Dependencies

Source: https://properdocs.org/user-guide/cli

Shows required PyPI packages inferred from plugins in properdocs.yml. Use --config-file to specify a configuration file.

```bash
properdocs get-deps [OPTIONS]
```

--------------------------------

### User Configuration for List of Complex Items

Source: https://properdocs.org/dev-guide/plugins

Example of a user-provided configuration for a list of complex items, matching the `ListOfItems(SubConfig)` schema.

```yaml
my_plugin:
  add_rectangles:
    - width: 5
      height: 7
    - width: 12
      height: 2
```

--------------------------------

### Enable a Plugin in Configuration

Source: https://properdocs.org/dev-guide/plugins

List the desired plugin name in the `plugins` configuration option to enable it. The plugin must be installed prior to enabling.

```yaml
plugins:
  - search
```

--------------------------------

### Install MkDocs Dependencies

Source: https://properdocs.org/about/release-notes

Use this command to automatically detect and install Python dependencies required for a MkDocs site build. It scans configuration files for themes, plugins, and extensions.

```bash
pip install $(mkdocs get-deps)
```

--------------------------------

### Configure Read the Docs Theme

Source: https://properdocs.org/user-guide/choosing-your-theme

Configure the 'readthedocs' theme in your project's configuration file. This example enables syntax highlighting and specifies additional languages.

```yaml
theme:
  name: readthedocs
  highlightjs: true
  hljs_languages:
    - yaml
    - rust
```

--------------------------------

### Enable Prebuild Search Index

Source: https://properdocs.org/user-guide/configuration

Enable the generation of a pre-built search index for performance improvements on larger sites. Requires Node.js to be installed.

```yaml
plugins:
  - search:
      prebuild_index: true
```

--------------------------------

### User Configuration for Plugin Schema

Source: https://properdocs.org/dev-guide/plugins

Example of a user-provided configuration that conforms to the defined plugin schema. This structure is parsed and validated by ProperDocs.

```yaml
my_plugin:
  definition_file: configs/test.ini  # relative to properdocs.yml
  validation:
    enabled: !ENV [CI, false]
    verbose: true
    skip_checks:
      - foo
      - baz
```

--------------------------------

### Upgrade ProperDocs

Source: https://properdocs.org/about/release-notes

Use this command to upgrade ProperDocs to the latest version. Ensure you have pip installed.

```bash
pip install -U properdocs
```

--------------------------------

### Example Directory Structure for Custom Theme

Source: https://properdocs.org/user-guide/customizing-your-theme

Illustrates the expected directory structure when using `theme.custom_dir` to override theme files like `404.html`, `favicon.ico`, and JavaScript libraries.

```text
- docs/
  - index.html
- custom_theme/
  - img/
    - favicon.ico
  - js/
    - somelib.js
  - 404.html
- config.yml
```

--------------------------------

### Configure Search Plugin Languages

Source: https://properdocs.org/user-guide/configuration

Specify a list of languages for the search index. This example includes multiple languages.

```yaml
plugins:
  - search:
      lang: [da, nl, en]
```

--------------------------------

### Example Hook Script Implementation

Source: https://properdocs.org/user-guide/configuration

A basic Python hook script that replaces all occurrences of 'a' with 'z' in the markdown content.

```python
def on_page_markdown(markdown, **kwargs):
    return markdown.replace('a', 'z')
```

--------------------------------

### Configure Edit URI with Hash Fragment

Source: https://properdocs.org/user-guide/configuration

This example demonstrates configuring `edit_uri` using a hash fragment, which is useful for repository hosts that use fragments to access files. Ensure `repo_url` is also set.

```yaml
edit_uri: "#root/path/docs/"
```

--------------------------------

### New Plugin Config Scheme (with type checker errors)

Source: https://properdocs.org/about/release-notes

This example demonstrates the new class-based configuration schema for plugins. It uses static type checking, and the inline comments highlight potential errors that a type checker like mypy would catch.

```python
from mkdocs import plugins
from mkdocs.config import base, config_options as c

class MyPluginConfig(base.Config):
    foo = c.Optional(c.Type(int))
    bar = c.Type(str, default='')

class MyPlugin(plugins.BasePlugin[MyPluginConfig]):
    def on_page_markdown(self, markdown: str, *, config: defaults.ProperDocsConfig, **kwargs):
        if self.config.foo < 5:  # Error, `foo` might be `None`, need to check first.
            if config.site_url.startswith('http:'):  # Error, MkDocs' `site_url` also might be `None`.
                return markdown + self.config.baz  # Error, no such attribute `baz`!
```

--------------------------------

### Define Plugin Configuration Scheme (Tuple)

Source: https://properdocs.org/dev-guide/plugins

Define the configuration scheme for a BasePlugin subclass using a tuple of validation instances. This example shows string, integer, and boolean types.

```python
class MyPlugin(properdocs.plugins.BasePlugin):
    config_scheme = (
        ('foo', properdocs.config.config_options.Type(str, default='a default value')),
        ('bar', properdocs.config.config_options.Type(int, default=0)),
        ('baz', properdocs.config.config_options.Type(bool, default=True))
    )
```

--------------------------------

### Define Plugin Configuration Scheme (Class)

Source: https://properdocs.org/dev-guide/plugins

For MkDocs 1.4+, define the config schema as a class inheriting from `properdocs.config.base.Config` for type safety benefits. This example defines string, integer, and boolean options.

```python
class MyPluginConfig(properdocs.config.base.Config):
    foo = properdocs.config.config_options.Type(str, default='a default value')
    bar = properdocs.config.config_options.Type(int, default=0)
    baz = properdocs.config.config_options.Type(bool, default=True)

class MyPlugin(properdocs.plugins.BasePlugin[MyPluginConfig]):
    ...
```

--------------------------------

### setup.py for ProperDocs Theme Package

Source: https://properdocs.org/dev-guide/themes

This setup.py file is essential for packaging your theme. Fill in the URL, license, description, author, and author email. The 'name' should follow the convention 'properdocs-themename'. The 'entry_points' section registers your theme with ProperDocs.

```python
from setuptools import setup, find_packages

VERSION = '0.0.1'

setup(
    name="properdocs-themename",
    version=VERSION,
    url='',
    license='',
    description='',
    author='',
    author_email='',
    packages=find_packages(),
    include_package_data=True,
    entry_points={
        'properdocs.themes': [
            'themename = theme_name',
        ]
    },
    zip_safe=False
)
```

--------------------------------

### Ignored Files in Theme Directory

Source: https://properdocs.org/dev-guide/themes

Examples of files and directories that ProperDocs will ignore within a theme directory. Files starting with a dot are explicitly ignored.

```text
.ignored.txt
.ignored/file.txt
foo/.ignored.txt
foo/.ignored/file.txt
```

--------------------------------

### Define Plugin Configuration Schema

Source: https://properdocs.org/dev-guide/plugins

Define a configuration schema for a plugin using `properdocs.config.base.Config`. This example shows how to use `Type`, `File`, `Optional`, `SubConfig`, and `ListOfItems` to create a structured and validated configuration.

```python
from properdocs.config import base, config_options as c

class _ValidationOptions(base.Config):
    enabled = c.Type(bool, default=True)
    verbose = c.Type(bool, default=False)
    skip_checks = c.ListOfItems(c.Choice(('foo', 'bar', 'baz')), default=[])

class MyPluginConfig(base.Config):
    definition_file = c.File(exists=True)  # required
    checksum_file = c.Optional(c.File(exists=True))  # can be None but must exist if specified
    validation = c.SubConfig(_ValidationOptions)
```

--------------------------------

### Anchor Declaration Examples

Source: https://properdocs.org/about/release-notes

Demonstrates various methods for declaring anchors in Markdown documents, including standard headings, custom anchors using attribute lists, and raw HTML anchors.

```markdown
## Heading producing an anchor
```

```markdown
## Another heading {#custom-anchor-for-heading-using-attr-list}
```

```html
<a id="raw-anchor"></a>
```

```markdown
[](){#markdown-anchor-using-attr-list}
```

--------------------------------

### Define Config with Reserved Word

Source: https://properdocs.org/about/release-notes

Example of adding an `async` boolean option to a configuration that can be set by the user as `async: true` and read programmatically as `config.async_`. This avoids clashing with Python's reserved words by stripping a trailing underscore.

```python
class ExampleConfig(Config):
    async_ = Type(bool, default=False)
```

--------------------------------

### Open Local Site in Browser with `mkdocs serve --open`

Source: https://properdocs.org/about/release-notes

Use the `--open` flag with `mkdocs serve` to automatically open the local site in your default browser after the initial build.

```bash
mkdocs serve --open
```

--------------------------------

### Build and Upload Documentation

Source: https://properdocs.org/user-guide/deploying-your-docs

Builds the documentation and then copies the generated site files to a remote server using scp. Replace placeholders with your actual server credentials and path.

```bash
properdocs build
scp -r ./site user@host:/path/to/server/root
```

--------------------------------

### Register Multiple Plugins in Setup.py

Source: https://properdocs.org/dev-guide/plugins

When a single Python package contains multiple plugins, register each one as a separate entry point under the `properdocs.plugins` key in your `setup.py` script.

```python
entry_points={
    'properdocs.plugins': [
        'featureA = path.to.my_plugins:PluginA',
        'featureB = path.to.my_plugins:PluginB'
    ]
}
```

--------------------------------

### Build MkLorum Documentation

Source: https://properdocs.org/getting-started

Run this command to build your MkLorum documentation. It generates a 'site' directory containing the static files for your documentation.

```bash
properdocs build
```

--------------------------------

### Serve Local Documentation Preview

Source: https://properdocs.org/about/contributing

Preview the ProperDocs site locally after making edits to files under the 'docs/' directory. Resolve any 'WARNING' messages before contributing.

```bash
hatch run docs:serve
```

--------------------------------

### Create a new ProperDocs project

Source: https://properdocs.org/user-guide/cli

Use this command to initialize a new ProperDocs project in the specified directory. Options allow for silencing warnings or enabling verbose output.

```bash
properdocs new [OPTIONS] PROJECT_DIRECTORY
```

--------------------------------

### View Build Command Options

Source: https://properdocs.org/getting-started

To see specific options for a command like 'build', use the --help flag with the command. This helps in customizing the build process.

```bash
properdocs build --help
```

--------------------------------

### View ProperDocs Help

Source: https://properdocs.org/getting-started

Use the --help flag to view all available commands and options for ProperDocs. This is useful for discovering functionality.

```bash
properdocs --help
```

--------------------------------

### Configure Output Directory Exclusion in Git

Source: https://properdocs.org/user-guide/configuration

Example of how to ignore the site output directory in Git.

```git
site/
```

--------------------------------

### Configure Plugins with List Syntax

Source: https://properdocs.org/user-guide/configuration

Use this syntax to define a list of plugins to be used during site building. Defaults are ignored if this setting is defined.

```yaml
plugins:
  - search
  - your_other_plugin
```

--------------------------------

### Example Anchor Warning Message

Source: https://properdocs.org/about/release-notes

Illustrates a typical warning message generated by MkDocs when a linked anchor is not found in the target document.

```text
WARNING -  Doc file 'foo/example.md' contains a link '../bar.md#some-heading', but the doc 'foo/bar.md' does not contain an anchor '#some-heading'.
```

--------------------------------

### Initialize Translation Catalog

Source: https://properdocs.org/dev-guide/translations

Use this command to create a new language catalog for a theme. Specify the input POT file and the output directory for the PO files, along with the desired language code.

```bash
pybabel init --input-file packages/properdocs-theme-mkdocs/properdocs_theme_mkdocs/messages.pot --output-dir packages/properdocs-theme-mkdocs/properdocs_theme_mkdocs/locales -l es
pybabel init --input-file packages/properdocs-theme-readthedocs/properdocs_theme_readthedocs/messages.pot --output-dir packages/properdocs-theme-readthedocs/properdocs_theme_readthedocs/locales -l es
```

--------------------------------

### Create a New ProperDocs Project

Source: https://properdocs.org/getting-started

Generates a new ProperDocs project and navigates into its directory. This sets up the initial configuration and documentation structure.

```bash
properdocs new my-project
cd my-project
```

--------------------------------

### Configure Theme with Key/Value Pairs

Source: https://properdocs.org/user-guide/configuration

Sets the theme and theme-specific configuration. Use key/value pairs for detailed customization.

```yaml
theme:
  name: mkdocs
  locale: en
  custom_dir: my_theme_customizations/
  static_templates:
    - sitemap.html
  include_sidebar: false
```

--------------------------------

### Get Plugin Logger

Source: https://properdocs.org/about/release-notes

Use this idiom to opt into a standardized way for plugins to log messages. It requires importing `get_plugin_logger` from `properdocs.plugins`.

```python
log = properdocs.plugins.get_plugin_logger(__name__)
...
log.info("Hello, world")
```

--------------------------------

### Configure Directories to Watch

Source: https://properdocs.org/user-guide/configuration

Specify additional directories to monitor for changes when running `properdocs serve` using a YAML list. Paths are relative to the configuration file.

```yaml
watch:
  - directory_a
  - directory_b
```

--------------------------------

### Build with Config from Stdin

Source: https://properdocs.org/about/release-notes

Use this command to provide configuration overrides on the fly by piping the config to stdin. This was a regression in previous versions.

```bash
mkdocs build -f -
```

--------------------------------

### Configure Theme Custom Directory

Source: https://properdocs.org/user-guide/customizing-your-theme

Set `theme.custom_dir` to a directory containing files that override the parent theme. Ensure `theme.name` is set to an installed theme.

```yaml
theme:
  name: mkdocs
  custom_dir: custom_theme/
```

--------------------------------

### Configure Search Plugin Minimum Query Length

Source: https://properdocs.org/user-guide/configuration

Set the minimum length for a search query. This example reduces the minimum length to 2 characters.

```yaml
plugins:
  - search:
      min_search_length: 2
```

--------------------------------

### Run ProperDocs on Windows using py launcher

Source: https://properdocs.org/user-guide/installation

Alternative command for running ProperDocs on Windows using the 'py -m' prefix.

```bash
py -m properdocs
```

--------------------------------

### Basic Project File Layout

Source: https://properdocs.org/user-guide/writing-your-docs

A minimal project structure for documentation, including the configuration file and the main index Markdown file.

```yaml
properdocs.yml
docs/
    index.md
```

--------------------------------

### Conditionally Enable a Plugin

Source: https://properdocs.org/user-guide/configuration

Use the 'enabled' boolean option to conditionally activate a plugin. This example uses an environment variable to control the 'code-validator' plugin.

```yaml
plugins:
  - search
  - code-validator:
      enabled: !ENV [LINT, false]
```

--------------------------------

### Translate Message String

Source: https://properdocs.org/dev-guide/translations

This is an example of a Portable Object (PO) file entry. Translate the text within the `msgstr` field, ensuring not to modify the `msgid`.

```gettext
msgid "Next"
msgstr "Siguiente"
```

--------------------------------

### Configure Search Plugin Separator

Source: https://properdocs.org/user-guide/configuration

Customize the word separator regular expression for the search plugin's index building. This example adds the dot (.) as a separator.

```yaml
plugins:
  - search:
      separator: '[\s\-\.]+'
```

--------------------------------

### Deploy Project Docs to GitHub Pages

Source: https://properdocs.org/user-guide/deploying-your-docs

Use this command to build and deploy your project's documentation to the `gh-pages` branch on GitHub. It automatically handles building and committing changes.

```bash
properdocs gh-deploy
```

--------------------------------

### on_env Event

Source: https://properdocs.org/dev-guide/plugins

The `env` event is called after the Jinja template environment is set up, allowing plugins to modify the environment, for example, by adding custom filters or globals.

```APIDOC
## on_env

### Description
The `env` event is called after the Jinja template environment is created and can be used to alter the Jinja environment.

### Parameters
- **`env`** (`Environment`) - Description: global Jinja environment
- **`config`** (`ProperDocsConfig`) - Description: global configuration object
- **`files`** (`Files`) - Description: global files collection

### Returns
- `Environment | None` - Description: global Jinja Environment
```

--------------------------------

### Configure Plugins with Key/Value Syntax

Source: https://properdocs.org/user-guide/configuration

An alternative syntax for plugin configuration where plugins are defined as key/value pairs. An empty value must be provided for plugins without options.

```yaml
plugins:
  search: {}
  your_other_plugin:
    option1: value
    option2: other value
```

--------------------------------

### Configure Theme Locale in properdocs.yml

Source: https://properdocs.org/user-guide/localizing-your-theme

Set the locale parameter in your `properdocs.yml` configuration file to specify the desired language for the theme. For example, set to 'fr' for French.

```yaml
theme:
  name: mkdocs
  locale: fr
```

--------------------------------

### Enable Absolute Link Validation

Source: https://properdocs.org/about/release-notes

Configure MkDocs to treat absolute links starting with '/' as relative to the docs directory. This setting enables validation for these links.

```yaml
validation:
  links:
    absolute_links: relative_to_docs
```

--------------------------------

### Migrating from mkdocs-simple-hooks

Source: https://properdocs.org/user-guide/configuration

Shows how to replace the 'mkdocs-simple-hooks' plugin configuration with the native ProperDocs 'hooks' configuration.

```yaml
-plugins:
-  - mkdocs-simple-hooks:
-      hooks:
-        on_page_markdown: 'my_hooks:on_page_markdown'
+hooks:
+  - my_hooks.py
```

--------------------------------

### Define Multiple Handlers for One Event with CombinedEvent

Source: https://properdocs.org/dev-guide/plugins

Use `CombinedEvent` to register multiple handlers for the same event, each potentially with a different priority. Sub-method names cannot start with `on_`.

```python
from properdocs.plugins import CombinedEvent, event_priority

@event_priority(100)
def _on_page_markdown_1(self, markdown: str, **kwargs):
    ...

@event_priority(-50)
def _on_page_markdown_2(self, markdown: str, **kwargs):
    ...

on_page_markdown = CombinedEvent(_on_page_page_markdown_1, _on_page_markdown_2)
```

--------------------------------

### Corrected Plugin Config Scheme

Source: https://properdocs.org/about/release-notes

This corrected example shows how to resolve the type checker errors from the previous snippet by adding null checks and ensuring correct attribute access.

```python
class MyPlugin(plugins.BasePlugin[MyPluginConfig]):
    def on_page_markdown(self, markdown: str, *, config: defaults.ProperDocsConfig, **kwargs):
        if self.config.foo is not None and self.config.foo < 5:  # OK, `int < int` is valid.
            if (config.site_url or '').startswith('http:'):  # OK, `str.startswith(str)` is valid.
                return markdown + self.config.bar  # OK, `str + str` is valid.
```

--------------------------------

### Add Translation Markers to HTML Templates

Source: https://properdocs.org/dev-guide/themes

Example of wrapping translatable text in HTML templates using Jinja's `{% trans %}` and `{% endtrans %}` syntax. This is part of the localization workflow.

```html
---
--- a/basic_theme/base.html
+++ b/basic_theme/base.html
@@ -88,7 +88,7 @@

 <body>

-  <h1>This is an example theme for ProperDocs.</h1>
+  <h1>{% trans %}This is an example theme for ProperDocs.{% endtrans %}</h1>

   <p>
     It is designed to be read by looking at the theme HTML which is heavily

```

--------------------------------

### Accessing Theme Configuration in Templates

Source: https://properdocs.org/dev-guide/themes

Theme configuration options defined in mkdocs_theme.yml are accessible within your templates via the 'config.theme' object. This example shows how to conditionally render a sidebar.

```html
{% if config.theme.show_sidebar %}
<div id="sidebar">...</div>
{% endif %}
```

--------------------------------

### Modify Theme Config in on_config Event

Source: https://properdocs.org/dev-guide/plugins

Example of modifying the theme configuration within the `on_config` event handler by adding a static template. The modified config object should be returned.

```python
class MyPlugin(BasePlugin):
    def on_config(self, config, **kwargs):
        config['theme'].static_templates.add('my_template.html')
        return config
```

--------------------------------

### Basic Navigation Configuration

Source: https://properdocs.org/user-guide/configuration

Define a simple navigation structure for your site using a list of Markdown files. Paths are relative to `docs_dir`.

```yaml
nav:
  - 'index.md'
  - 'about.md'
```

--------------------------------

### Create Virtual File with Content

Source: https://properdocs.org/dev-guide/api

Use this class method to create a virtual file. Provide content directly or specify an absolute path to an existing file. The `src_uri` determines its location within the documentation structure.

```python
generated(config: ProperDocsConfig, src_uri: str, *, content: str | bytes, inclusion: InclusionLevel = InclusionLevel.UNDEFINED) -> File
```

--------------------------------

### Nested Directory File Layout

Source: https://properdocs.org/user-guide/writing-your-docs

Demonstrates organizing documentation source files in nested directories for better structure.

```yaml
docs/
    index.md
    user-guide/getting-started.md
    user-guide/configuration-options.md
    license.md
```

--------------------------------

### Deploy Organization/User Docs to GitHub Pages

Source: https://properdocs.org/user-guide/deploying-your-docs

Deploy documentation for organization or user pages. This requires changing to the dedicated repository and specifying the config file and remote branch.

```bash
cd ../orgname.github.io/
properdocs gh-deploy --config-file ../my-project/properdocs.yml --remote-branch master
```

--------------------------------

### Configure Edit URI with Relative Path

Source: https://properdocs.org/user-guide/configuration

Set `edit_uri` to a relative path to the docs directory for hosts that do not use query strings or fragments. This example uses a simple relative path.

```yaml
edit_uri: root/path/docs/
```

--------------------------------

### Enable Markdown Extension

Source: https://properdocs.org/user-guide/configuration

Enable the SmartyPants typography extension by adding it to the markdown_extensions list.

```yaml
markdown_extensions:
  - smarty
```

--------------------------------

### Configure Edit URI with Query String

Source: https://properdocs.org/user-guide/configuration

When `repo_url` is set, `edit_uri` specifies the path to the docs directory in your repository. This example shows how to configure it using a query string for specific repository hosts.

```yaml
edit_uri: "?query=root/path/docs/"
```

--------------------------------

### Configure Plugins with Options

Source: https://properdocs.org/user-guide/configuration

Define options for a plugin by using nested key/value pairs within the plugin's entry in the plugins list.

```yaml
plugins:
  - search
  - your_other_plugin:
      option1: value
      option2: other value
```

--------------------------------

### Basic Navigation Configuration

Source: https://properdocs.org/user-guide/writing-your-docs

Defines a simple navigation menu with two top-level pages. Paths are relative to `docs_dir`.

```yaml
nav:
  - index.md
  - about.md
```

--------------------------------

### Configure for Local File Viewing

Source: https://properdocs.org/user-guide/deploying-your-docs

Sets the site_url to an empty string to enable building the site for the file:// scheme. This is necessary for offline viewing.

```yaml
site_url: ""
```

--------------------------------

### YAML Style Meta-Data Example

Source: https://properdocs.org/user-guide/writing-your-docs

Use YAML style meta-data wrapped in '---' or '...' delimiters. The content is parsed as YAML, resulting in a Python dict. Keys are case-sensitive and expected to be lowercase.

```markdown
---
title: My Document
summary: A brief description of my document.
authors:
    - Waylan Limberg
    - Tom Christie
date: 2018-07-10
some_url: https://example.com
---
This is the first paragraph of the document.
```

--------------------------------

### ProperDocs Build Command

Source: https://properdocs.org/user-guide/cli

Builds the ProperDocs documentation. Use the --clean option to remove old files before building, or --strict to abort on warnings.

```bash
properdocs build [OPTIONS]
```

--------------------------------

### Configure word separator for TOC IDs

Source: https://properdocs.org/user-guide/writing-your-docs

Customize the `separator` in `properdocs.yml` to change the character used to replace whitespace in generated header IDs. For example, use an underscore instead of the default dash.

```yaml
markdown_extensions:
  - toc:
      separator: "_"
```

--------------------------------

### Get Plugin Logger Convenience Function

Source: https://properdocs.org/dev-guide/plugins

Utilize the `get_plugin_logger` function for a simplified way to obtain a logger that is automatically prefixed with the plugin's name, ensuring consistent log formatting within ProperDocs.

```python
from properdocs.plugins import get_plugin_logger

log = get_plugin_logger(__name__)
log.info("My plugin message")
```
Tokens:
Raw