This project is experimental and in flux. Stay tuned an/or join us ;-)
- open source
- open framework for plugins, invoked depending on their
{% tag %} - downwards compatible, i.e. a superset of Markdown and MultiMarkdown
- providing access to the parse tree (DOM) (use it as a library)
- a Markdown preprocessor or stand-alone md replacement
- richer self-contained documents
- include or embed other text files
- ready for web-publication beyond images and quotes
- a computable document by allowing Python code
${import math; math.pi} - clean pure Python parser instead of a huge f.?ck(i)ng RegEx
- plugins have access to the parsing tree (DOM)
- a plugin-collection to extend Markdown functionality
-
Generated table of contents with links
- The output of
{% toc %}should be markdown links to the headings.
- The output of
-
Wiki style [[links]].
-
Tables like in MultiMarkdown and Pandoc.
-
Including other text/markdown/html files as-is
{% include file.html %}
-
Embedding other text/markdown/html as-it (will be copied into the md file)
{% embed file.html --> <body> <h1>From outer space</h1> </body> %} -
Bibliography and citing
-
A recipe plugin that generates embedded JavaScript to dynamically compute the amounts of the ingredients when one changes the number of persons.
-
Integration with Python/IPython
-
Simple computations in tables like a mini spreadsheet
-
Shell out, if you really have to
{%sh echo "spam" %}
(However, I would avoid using this as long as you can embed the output as an image or plain text and usemakeor another build system to decide when to build what.)
Remarkable is inspired by MultiMarkdown, Pandoc, markdown2.py, Jinja2, Octopress and others. Adding your own new tags and features is easy.
Markdown is designed to be a "easy-to-read, easy-to-write plain text format" that looks nice in plain text but still defines markup in a machine readable manner to create pleasing output. These properties render it perfect for syncing, version control, exchanging notes with colleagues, avoiding lock-ins.
Planning phase. Getting the goals right. Finding the right technoloy. Pretty much experimenting around.
- ☐ Basic source file layout
- ☐ Write regression tests against other markdown implementations.
- ☐ Writing a simple markdown parser in pyparsing
- ☐ Performance check
Remakrable calls plugins on certain tags.
-
{%TAG(ARGS) --> EVALUATED %}
This is the most general form. The parenthesis is optional and spaces or newlines are allowed. The-->will be automatically added. EVALUATED will be replaced (overwritten in the md source file) with the result of the plugin. The final output (HTML) will only containEVALUATED.- The EVALUATED part can span multiple lines.
- If there is no
-->, then one will be added by Remarkable.
-
Alternative form: Its possible to use a new line (then no
-->will be added/needed){% TAG ARG1 ARG2 EVALUATED %} -
Alternative opening/closing tags to optionally make the plugin instructions invisible if you use another markdown converter.
- Instead of
{%:<!--{% - Instead of
%}:<!--%}-->
- Instead of
-
$`foo="spam"`
to show Python code and evaluate it but without inserting the result. -
${foo}
to insert the value of a Python variable (or function). Example: This is ${foo}! will result to: "This is spam!" -
{{foo}}
to show the Python code, evaluate it and insert the result. The above command would result in something that looks more like an IPython notebook with input and output cells.`foo` spam
-
I really, really want to keep the source readable and I don't want another LaTeX with it's cryptic error messages and source code that looks no longer human readable. Have you tried a table in LaTeX? Sucks. When in doubt, we will decide for the simpler form even if the one or other feature is not covered.
-
Only one pass through the document, not multiple passes or loops such as some template engines do. KISS.
-
Provide a document object model tree (DOM) to the plug-ins. This would enable things like writing a simple "sum" plugin for a table (see below).
sumwithout arguments could automatically assume to add all values in the current row above (but without the heading).
| Month | 2012 | 2013 |
|---|---|---|
| Jan | 33.0 | 42.0 |
| Feb | 7.2 | 6.5 |
| Mar | 20.2 | 10.0 |
| SUM | {% sum --> 60.4 %} | {% sum [Jan-Mar] --> 58.5 %} |
-
From outside the table, we may want to be able to interact with the DOM from python:
So we see the cumulative total as${ DOM.tables[0]["2012"]["SUM"] + DOM.tables[0]["2013"]["SUM"] } -
Allow to define variables and access them in a later
${tag}. A bottle of milk costs$`Euro=0.89`, so$`n=3`bottles cost${Euro * n}Euro. It should result to:
"A bottle of milk costs Euro=0.89, so n=3 bottles cost 2.67 Euro." -
Nested tags
{% embed_image ${ import matplotlib.pyplot as ppt ppt.plot([1,2,5,4,1]) ppt.savefig('img1.svg') print('img1.svg') } %} -
Ideally nesting should support piping the data and avoid writing files.
-
(Re-)implement some of the more often used plugins that octopress provides and make the tags compatible so that the same markdown file works on both. We could even have a regression check to compare both systems.
-
If you want other markdowners not to print the special tags we could support
<!--%}(with optional whitespace before the "%") as the closing tag and-->as the tag after which the generated content is inserted:<!-- {% python print("Hello!") --> <!-- %} -->
todo
If you have remark(.py) in your PATH:
remark README.md > out.html
else:
python path/to/remark.py README.md > out.html
-
Using a style sheet:
python remark.py -s style.css README.md > out.html -
Embedding: Attempt to make a single self-contained html-file by embeding all images (base64 encoding)and stylesheets into the document.
python remark.py --embed -s style.css -f README.md > out.html