Metadata-Version: 2.1
Name: pelican-markdown-unrendered-metadata
Version: 0.1.0
Summary: Read Pelican metadata from link references
Home-page: https://github.com/BoniLindsley/pelican-markdown-unrendered-metadata
Author: Boni Lindsley
Author-email: boni.lindsley@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: Markdown (>=3.3.4")
Requires-Dist: pelican (>=4.7.1")
Provides-Extra: dev
Requires-Dist: Markdown (>=3.3.4) ; extra == 'dev'
Requires-Dist: Sphinx (>=4.2.0) ; extra == 'dev'
Requires-Dist: black (>=21.9b0) ; extra == 'dev'
Requires-Dist: coverage[toml] (>=6.0.2) ; extra == 'dev'
Requires-Dist: mypy (>=0.910) ; extra == 'dev'
Requires-Dist: pytest (>=6.2.5) ; extra == 'dev'
Requires-Dist: recommonmark (>=0.7.1) ; extra == 'dev'
Requires-Dist: tox (>=3.24.4) ; extra == 'dev'
Requires-Dist: types-Markdown (>=3.3.6) ; extra == 'dev'
Requires-Dist: types-appdirs (>=1.4.1) ; extra == 'dev'
Requires-Dist: types-pkg-resources (>=0.1.3) ; extra == 'dev'
Requires-Dist: types-six (>=1.16.2) ; extra == 'dev'

Pelican Markdown Unrendered Metadata
====================================

Read Pelican metadata from link references.

Usage
-----

Write metadata in the form `[//Pelican/KEY]: # (VALUE)`.
They can be placed anywhere in the document.
If the first text content is a top-level heading,
the heading is removed from the document, and used as the title.
For example,

```md
# Hello, world!

[//Pelican/date]: # (2000-10-31 00:00)
[//Pelican/author]: # (Noname)

Goodbye, world!
```

The equivalent MultiMarkdown document used by Pelican would be

```md
title: Hello, world!
date: 2000-10-31 00:00
author: Noname

Goodbye, world!
```

If a key has multiple sources (references, MultiMarkdown, heading),
the order of stored value is unspecified.

Installation
------------

If `PLUGINS` is not specified inside `pelicanconf.py`,
then installing this package should be sufficient setup.
Otherwise, inside `pelicanconf.py`,
add `markdown_unrendered_metadata` to the `PLUGINS` list variable.

If copying the plugin is preferred,
add the `src` directory to the `PLUGIN_PATHS` list variable.
For example, if this `README.md` file is at the path
`${project_root}/plugins/pelican-markdown-unrendered-metadata/README.md`,
then the two variables in `${project_root}/pelicanconf.py` should contain

```py
PLUGINS = [
  'markdown_unrendered_metadata',
]
PLUGIN_PATHS = [
  'plugins/pelican-markdown-unrendered-metadata/src',
]
```

Raison d'être
-------------

Pelican metadata of Markdown documents
are colon-separated key-value pairs at the beginning of the document.
Markdown parsers see them as a block of text
and generate an unintended paragraph when rendered.

To mitigate this, the metadata can be embedded
inside a form of Markdown comments.
This plugin uses link references as comments, suggested by a
[StackOverflow answer](https://stackoverflow.com/a/20885980):

```md
[//]: # (This may be the most platform independent comment)
```


