Skip to main content

Definition of Feedmark, a curation-oriented subset of Markdown, and tools for processing it

Project description

Feedmark

Version 0.9. Subject to change in backwards-incompatible ways without notice.

Feedmark is a format for embedding structured data in Markdown files in a way which is both human-readable and machine-extractable. The structured data is intended to be "curational" in nature. Articles in Chrysoberyl and The Dossier are written in Feedmark.

Informally, the format says that every h3-level heading in the Markdown file gives the title of an entity, and may be followed immediately by the entity's "plaque", which is a bullet list where every item is in the form "field-name: field-value".

Why Feedmark?

In the same way that a Markdown file is still a readable text file, which is nice, a Feedmark file is still a readable Markdown file, which is still a readable text file, which is nice.

While some structured data formats like YAML are fairly easy to read, many web-based files viewers (such as GitHub's) will automatically format Markdown as HTML, making it that much nicer.

Example Feedmark documents can be found in the eg/ directory, and in the projects mentioned above.

Implementation

This repository contains a Python program, feedmark, which is a reference implementation of a processor for the Feedmark format.

To use it, you can clone this repository and run it as bin/feedmark from the directory of your clone, or you can put the bin directory on your executable search path, and run it as feedmark anywhere.

Or you can install it using pip:

pip install -e git://github.com/catseye/Feedmark.git@0.9#egg=feedmark

(Depending on your needs, you may wish to establish a virtual environment first.)

feedmark is currently able to do the following things:

Parse and check Feedmark documents

Loading documents will always check that they are minimally well-formed.

feedmark eg/*.md

You can also check documents against a Feedmark schema, which is simply another Feedmark document, one in which each entry describes a property that entries should have.

feedmark eg/*Sightings*.md --check-against=eg/schema/Llama\ sighting.md

Convert Feedmark documents to various formats

The original use case of this tool was to generate an Atom (née RSS) feed of entries in a document:

feedmark "eg/Recent Llama Sightings.md" --output-atom=feed.xml
python -m SimpleHTTPServer 7000 &
python -m webbrowser http://localhost:7000/feed.xml

It can now also output entries as JSON, indexed by entry, or by property, or by publication date:

feedmark --output-json eg/*.md
feedmark --by-property eg/*.md
feedmark --by-publication-date eg/*.md

Output entries as Markdown, or HTML (using the toc extension, which generates link anchors on headings compatible with the ones generated by GitHub).

feedmark --output-markdown eg/*.md
feedmark --output-html eg/*.md

Rewrite documents in-place

They will be parsed as Feedmark, and then output as Markdown, to the same files that were read in as input. (Note! This is destructive; it is recommended that the original files be under version control such as git, which will easily allow the changes to be reverted if necessary.)

feedmark --rewrite-markdown eg/*.md

Interlink documents

Markdown supports "reference-style" links, which are not inline with the text.

feedmark can rewrite reference-style links that match the name of an entry in a previously-created "refdex", so that they can be kept current and point to the canonical document in which the entry exists, since it may exist in multiple, or be moved over time.

feedmark eg/*.md --output-refdex >refdex.json
feedmark --input-refdex=refdex.json --rewrite-markdown eg/*.md

See also

Feedmark is a subset of Markdown, which is something it has in common with Falderal, however it has decidedly different goals.

TODO

Research whether JSON Schema could be used for validation as well.

"common" properties on document which all entries within inherit.

Sub-entries. Somehow. For individual games in a series, implementations or variations on a programming language, etc.

Allow trailing ### on h3-level headings.

Index creation from refdex, for permalinks.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

Feedmark-0.9.tar.gz (13.3 kB view details)

Uploaded Source

Built Distribution

Feedmark-0.9-py3-none-any.whl (13.3 kB view details)

Uploaded Python 3

File details

Details for the file Feedmark-0.9.tar.gz.

File metadata

  • Download URL: Feedmark-0.9.tar.gz
  • Upload date:
  • Size: 13.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.15.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.4.0 requests-toolbelt/0.9.1 tqdm/4.36.1 CPython/3.5.2

File hashes

Hashes for Feedmark-0.9.tar.gz
Algorithm Hash digest
SHA256 a438c67885f779f7dbac8a4bc16b1780d151a6af0b579cddcca9608bd23a6583
MD5 d3896c12a5e658c439261a13dd6ac2a8
BLAKE2b-256 2bde6e3e58091b09d031a35c7d6ab0cb95a268f6da191bac6aa7c081a5d87cda

See more details on using hashes here.

File details

Details for the file Feedmark-0.9-py3-none-any.whl.

File metadata

  • Download URL: Feedmark-0.9-py3-none-any.whl
  • Upload date:
  • Size: 13.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.15.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.4.0 requests-toolbelt/0.9.1 tqdm/4.36.1 CPython/3.5.2

File hashes

Hashes for Feedmark-0.9-py3-none-any.whl
Algorithm Hash digest
SHA256 e43f5416d4488166f743d0ad2f3cc7127b80614304f40dbb666c4fd787061db3
MD5 355836875fc90d5a2b5c21ec2c35823a
BLAKE2b-256 e2b71035b3dac221bd27546936cc8d2c23e16bfb4c9a8b9a9e6755b216e6d714

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page