Skip to content

Preprocess markdown

Novella provides built-in Markdown preprocessing functionality to replace tags with automatically generated content. Tags are either specified as their own block written as @tag <args> or inline as {@link <args>}. Block tags can span multiple lines if the following lines are indented. Tags may have a TOML configuration following the keyword :with.

build.novella
do "preprocess-markdown" {
  path = "content/"
  use "pydoc"  # Requires Pydoc-Markdown (see https://github.com/NiklasRosenstein/pydoc-markdown)
}

Class MarkdownPreprocessorAction

class MarkdownPreprocessorAction(Action)

[view_source]

An action to preprocess Markdown files. All functionality of the processor is implemented by plugins that implement the MarkdownPreprocessor interface. The order of execution of the processors is based on their dependencies, much like when Actions are executed.

As a final step, the processor will process escaped inline tags (i.e. replacing {@ with @{).

path

The path to the folder in which markdown files should be preprocessed. If this is not set, all Markdown files in the build directory will be preprocessed.

encoding

The encoding to read and write files as.

update_with

def update_with(func: t.Callable[[MarkdownPreprocessor], None]) -> None

[view_source]

Adds a callback that can modify the MarkdownPreprocessor before it executes.

use

def use(processor: str | MarkdownPreprocessor,
        closure: _Closure | None = None,
        name: str | None = None) -> None

[view_source]

Register a processor for use in the plugin.

preprocessor

def preprocessor(processor_name: str,
                 closure: _Closure | None = None) -> MarkdownPreprocessor

[view_source]

Access or reconfigure a markdown processor that is already registered.

repeat

def repeat(path: Path,
           output_path: Path,
           content: str,
           source_path: Path | None = None,
           last_processor: MarkdownPreprocessor | None = None) -> str

[view_source]

Repeat all processors that have been processed so far on the given files. This is used by the @cat preprocessor to apply all preprocessors previously run on the newly included content. This does not include the processor that this method is called from, but only the preprocessors that preceded it. The caller may pass itself to the last_processor argument to include themselves.

execute

def execute(build: BuildContext) -> None

[view_source]

Execute the preprocessor on all Markdown files specified in path.

Class MarkdownPreprocessor

class MarkdownPreprocessor(Node['MarkdownPreprocessor'])

[view_source]

Interface for plugins to process markdown files.

ENTRYPOINT

The entrypoint under which preprocessor plugins must be registered.

setup

def setup() -> None

[view_source]

Called before the execution order of processors is determined.

process_files

@abc.abstractmethod
def process_files(files: MarkdownFiles) -> None

[view_source]

Process the file contents in files.