█ ▗▖
▀ ▐▌ ▐▌
█ █ █▟█▌ ██ ▐███ ▟█▙ ▟█▟▌ ▟█▙ █ █▐▙██▖
▜ █ ▛ █▘ █ ▐▌ ▐▙▄▟▌▐▛ ▜▌▐▛ ▜▌▜ █ ▛▐▛ ▐▌
▐▙█▟▌ █ █ ▐▌ ▐▛▀▀▘▐▌ ▐▌▐▌ ▐▌▐▙█▟▌▐▌ ▐▌
▝█ █▘ █ ▗▄█▄▖ ▐▙▄ ▝█▄▄▌▝█▄█▌▝█▄█▘▝█ █▘▐▌ ▐▌
▀ ▀ ▀ ▝▀▀▀▘ ▀▀ ▝▀▀ ▝▀▝▘ ▝▀▘ ▀ ▀ ▝▘ ▝▘
A slick and static academic publisher
Writedown is a set of shell scripts to generate books and articles fit for academic review and publishing. It can be operated on any device running ZShell, chapters can be written in Markdown syntax and it uses Latex rendering via Pandoc to produce DOCX, Latex or PDF documents. It sports automatic generation of the table of contents and the bibliographic section built out of a bibtex file and simple references across the text.
Writedown is designed after WebNomad and it is operated in a similar fashion, while both programs are compatible and can coexist on the same reposiroty, to generate both articles and webpages from the same text.
Writedown is at an early stage of development. The author's main motivation to create this software has been that of writing a Ph.D. thesis using Emacs, yet it may be used with different editors and for different purposes.
Writedown requires the installation of the Zsh shell, present by default or easily installable in most operating systems. In addition to that also a recent version of Pandoc is required, preferably version 1.17 or any later version, providing the "citeproc" extension to handle bibliographic citations.
If installed from its Git repository, then its necessary also to download the zuper submodule using the command:
git submodule update --init
First create a directory for your article, then place the writedown directory inside it, i.e. the one downloaded from the source archive or git repo.
From a terminal, cd inside your new article's directory and run:
./writedown/init
the skeleton of your new webpage is created inside the directory:
config.zsh -> contains title and general configurations
views/*.md -> each file is a chapter written
views/index.txt -> the order of chapters, one per line
views/template.tex -> custom template for latex/pdf render
views/abstract.txt -> contains the abstract of the article
views/references.bib -> contains bibtex entries
To render final results, run ./writedown/render and your article
will be in the pub/ directory.
When used, the first argument of the render command can be one of the three supported formats:
./writedown/render pdf
./writedown/render docx
./writedown/render latex
For more custom rendering solutions, see config.zsh and the commented
settings WRITEDOWN_OUTPUT_FORMAT and WRITEDOWN_OUTPUT_EXTENSION
which can be configured to match the output format for pandoc and the
extension of the resulting file.
In addition to the first argument indicating the extension, a second argument may be present to indicate the rendering of a single section (i.e. markdown source file) instead of the whole book index:
./writedown/render pdf chapter_one
The above command will render the file chapter_one.md found in the
views/ directory.
If error occur in the rendering it is possible to activate a more
verbose output by entering the DEBUG mode, this is simply done
prefixing the command as follows:
DEBUG=1 ./writedown/render pdf
Debugging output will include all latex rendering messages previous to the pdf rendering and any other information related to the command.
Upon installation of writedown on a default executable path, it is
possible to use it to render single markdown files placed anywhere in
a filesystem, without the need to init a new project directory.
One can simply invoke writedown-pdf or writedown-docx followed by
the path to a markdown source file and the result will be placed in
the current directiory; the dash suffix may support other extensions
too.
This is an experimental feature and can be easily improved as needs arise.
For integration with the blibliography manager Zotero, one should install the zotxt extension by downloading it from: https://addons.mozilla.org/firefox/downloads/latest/zotxt/addon-454106-latest.xpi
Then if using Emacs to edit markdown files is possible to install
the zotxt-emacs package from the
default MELPA repositories and activate the zotxt-easykey mode to run queries
using the C-c " k key combo.
Recent tests show that emacs queries via zotxt succeed but the pandoc support for the zotxt extension is not yet mature. Writedown will include the pandoc zotxt plugin inside its sourcecode when it will become stable, meanwhile one can help its development and troubleshooting at https://github.com/egh/zotxt
Bleeding edge is on GitHub. See https://github.com/dyne/writedown
Pull requests and translations of this documentation are welcome.
Come on IRC channel #dyne via https://irc.dyne.org to get in touch.
Money donations are very welcome and well needed
Writedown is Copyright (C) 2016-2017 by the Dyne.org Foundation
Writedown is designed, written and maintained by Denis Roio [email protected]
Thanks to reviews and contributions by James Barrit [email protected]
This program is free software: you can redistribute it and/or
modify it under the terms of the GNU Affero General Public License
as published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public
License along with this program. If not, see
http://www.gnu.org/licenses
