A ready-to-use framework to generate beautiful scientific documents, like journal articles, directly from Markdown text.
This is still a work in progress!
Is this for you?
- (want to) write your documents in Markdown (or AsciiDoc),
- and need a beautiful PDF or HTML version of your document,
- but also a Microsoft Word export,
then this is perfect for you!
This installation guide is written for Ubuntu, please adapt the commands to your operation system where needed. write*!* should work on all GNU/Linux distributions, as well as OS X and Windows.
Open up your favourite terminal and let’s go!
sudo apt-get install make git pandoc pandoc-citeproc asciidoctor xsltproc docbook-xsl fop unoconv
Ubuntu is normally pretty up-to-date on most of the required software. However you can optionally update Pandoc and/or Asciidoctor to their respective development versions to get the most out of you document.
Get a copy of this repository.
git clone email@example.com:and3k/write.git cd write git submodule update --init
Test your setup
Test if all the tools work.
make -B demo
The output of
make should look something like this and display no errors:
cp Content/Demo/Article_demo.md Output/Demo/Article_demo.md sed -i -f Content/Demo/rework.sed Output/Demo/Article_demo.md sed -i -f Core/rework_markdown.sed Output/Demo/Article_demo.md pandoc Output/Demo/Article_demo.md -o Output/Demo/Article_demo.adoc --filter pandoc-citeproc --no-wrap -t asciidoc sed -i -f Core/rework_asciidoc.sed Output/Demo/Article_demo.adoc asciidoctor --backend docbook --out-file Output/Demo/Article_demo.xml Output/Demo/Article_demo.adoc sed -i -f Core/rework_docbook.sed Output/Demo/Article_demo.xml xsltproc --output Output/Demo/Article_demo.fo Stylesheets/Demo/Article_demo.docbook_to_fo.xsl Output/Demo/Article_demo.xml Making portrait pages on A4 paper (210mmx297mm) sed -i -f Core/rework_fo.sed Output/Demo/Article_demo.fo fop -c Core/fop_config.xml -fo Output/Demo/Article_demo.fo -pdf Output/Demo/Article_demo.pdf [warning] /usr/bin/fop: No java runtime was found Picked up JAVA_TOOL_OPTIONS: -javaagent:/usr/share/java/jayatanaag.jar Font "Symbol,normal,700" not found. Substituting with "Symbol,normal,400". Font "ZapfDingbats,normal,700" not found. Substituting with "ZapfDingbats,normal,400". Rendered page #1. Rendered page #2. Rendered page #3. asciidoctor --out-file Output/Demo/Article_demo.fancy.html Output/Demo/Article_demo.adoc xsltproc --output Output/Demo/Article_demo.html Stylesheets/Demo/Article_demo.docbook_to_html.xsl Output/Demo/Article_demo.xml sed -i -f Core/rework_html.sed Output/Demo/Article_demo.html unoconv -d document --f doc Output/Demo/Article_demo.html Done: Output/Demo/Article_demo.pdf Output/Demo/Article_demo.fancy.html Output/Demo/Article_demo.doc
If you want to update write*!* to its newest version run:
cd write git pull make upgrade make -B all
cd write make Project_name/Document_name.article
This creates a new document named
Document_name.md in the folder
Content/Project_name/. Add your text (in Markdown), and run
make all to convert it to PDF, HTML, and Microsoft Word files. Those can then be found in the folder
cd write make My_first_paper/Main_text.article make My_first_paper/SI.article make all
Under the hood
Pandoc converts your Markdown document to AsciiDoc. Asciidoctor further converts it to DocBook, which gets converted to a FO and then a PDF file by xsltproc and FOP, respectively. In between write*!* adds a bit of magic here and there to make everything play together nicely. In parallel HTML files are generated by either Asciidoctor or xsltproc, and the later’s version is converted to a Word file with unoconv. unoconv is a document converter command-line interface for LibreOffice, so it could also be used to generate ODT or any other files supported by LibreOffice.
This setup allows for a hybrid approach the get the most out both Markdown/Pandoc and AsciiDoc/Asciidoctor, e.g.:
- Pandoc’s all powerful citeproc extension automatically generates fully formatted references, a feature not natively supported by Asciidoctor.
- Only AsciiDoc supports cross references.
In the YAML header of your document, you can set the following:
bibliography: this should point to your BibTeX file, which you can put in the folder
References/. Any other Pandoc-supported bibliography file and its location will work, but then documents will not be automatically updated if the bibliography file changes (see Known_issues.md).
csl: this should point to any of the citation styles located in the folder
Citation_styles/or be left empty. All publicly available CSL files are included for your convenience.
See also http://pandoc.org/README.html#citations.
Mixing Markdown and AsciiDoc syntax
With write*!* it’s possible to mix in some AsciiDoc into you Markdown documents. Any AsciiDoc syntax which can’t be interpreted by Pandoc as Markdown can be used.
In addition write*!* enables you to do the following:
- Use cross references in native AsciiDoc syntax (
<<reference-id>>), becaue Pandoc’s
raw_htmlextension is disabled.
- Multi-line blocks (e.g., AsciiDoc tables) will not work with their default syntax, because single new-lines are wrapped into one line by Pandoc. Thereby please add a number sign (
#) at the end of the line to preserve literal breaks.
includedirective can be used either with absolute or relative paths. However relative paths have to be relative to the AsciiDoc file, which is located in
Output/<Project name>/, not
Content/Demo/*.md for examples.
Help and Feedback
Known issues are listed in Known_issues.md.
Feel free to ask for help or submit feature requests, feedback, and issues at https://github.com/and3k/write/issues.
Please add the output of
make debug when appropriate.
Example output of