Content: Markdown

Content is written in Markdown with TOML front matter. Specifically, Blurry uses Mistune, along with a number of Blurry-specific customizations, to convert Markdown to HTML.

Here's what a basic about page might look like, using the AboutPage schema type:

+++
"@type" = "AboutPage"
name = "About Blurry"
abstract = "Learn about Blurry, a static site generator build for page speed and SEO"
datePublished = 2023-01-07
image = "../images/blurry-logo.png"
+++

# About Blurry

Regular Markdown content can go here.

Customizations

On top of Mistune's built-in plugins, Blurry ships with a number of Markdown customizations.

Links

Blurry converts relative file paths in Markdown to absolute paths in the build folder. For example:

[About](./about.md)

will be rendered as:

<a href="/about/">About</a>

External links are opened in a new tab and have the rel="noopener" attribute for security:

<a href="https://johnfraney.ca/" rel="noopener" target="_blank">John Franey</a>

Images

See Content: images for more information.

Videos

See Content: videos for more information.

Plugins

Punctuation

Blurry includes a plugin to convert certain punctuation shortcuts into the apporpriate characters. For example:

• --- is converted into an em dash (—)
• -- is converted into an en dash (–)

Container

Blurry ships with a "Container" plugin, which extends Mistune's Admonition directive and is useful for notes, warnings, and other asides. Its syntax is:

:::{info}
I'm an info paragraph!
:::

which renders as:

<aside role="note" class="info">
    <p>I'm an info paragraph!</p>
</aside>

Supported container names are:

• attention
• caution
• danger
• error
• hint
• important
• info
• note
• tip
• warning

Python Source Code

Blurry's Python Source Code plugin makes it easy to insert the source of a Python function, class, or other object into a document as a fenced code block.

For example, to show Blurry's internal MarkdownFileData type using the Python Source Code block syntax:

@python<blurry.types.MarkdownFileData>

will behave the same as:

```python
@dataclass
class MarkdownFileData:
    body: str
    front_matter: dict[str, Any]
    path: Path
```

but the Python source code will update on build if this type changes, unlike copying & pasting the code into a code block.