Tree @0.8 (Download .tar.gz)
Feedmark
Version 0.8. 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.
It is in the bin
directory, and can be run directly from there,
or bin
can be put on your search path.
It 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.
Commit History
@0.8
git clone https://git.catseye.tc/Feedmark/
- Merge pull request #8 from catseye/develop-0.8 Chris Pressey (commit: GitHub) 5 years ago
- Update HISTORY. Chris Pressey 5 years ago
- Add some example Javascript code for reading Feedmark properties. Chris Pressey 5 years ago
- Include the section's anchor in the outputted JSON as well. Chris Pressey 5 years ago
- Deep-HTMLize OrderedDicts as OrderedDicts. Chris Pressey 5 years ago
- Improve tests. Chris Pressey 5 years ago
- Properties in OrderedDict; --ordered-json serializes them as list. Chris Pressey 5 years ago
- Make sure this works with @-list properties. Chris Pressey 5 years ago
- When htmlizing property values, do not include enclosing paragraph. Chris Pressey 5 years ago
- Refactor Markdown->HTML5 helper function into format module. Chris Pressey 5 years ago