Minimalistic academic publisher using markdown and pandoc

Jaromil e56a5c1741 various fixes and updates to new pandoc 10 months ago
citstyle 739f91c41e bibliography, index and citation styles 2 years ago
extras e56a5c1741 various fixes and updates to new pandoc 10 months ago
test 35e6f65016 Fixing option to output LaTeX 2 years ago
zlibs a21af226b8 support for mkdocs config generation 1 year ago
zuper @ d49b98885d 1da1c81955 initial commit 2 years ago
.gitignore ce0ca97980 Removing writedown.log 2 years ago
.gitmodules 20d885cf13 template improvements 1 year ago
COPYING.txt 1da1c81955 initial commit 2 years ago
Cask 624d9b276a limit deps in cask installer for emacs 2 years ago
ChangeLog.md 1da1c81955 initial commit 2 years ago
Makefile a21af226b8 support for mkdocs config generation 1 year ago
README.md 74136daef7 typo 2 years ago
config.zsh e56a5c1741 various fixes and updates to new pandoc 10 months ago
deploy 9dda8e0df6 small fix to deploy 1 year ago
init 9ca08ca0b0 latex template configuration option 2 years ago
latex-template.tex 3ed33db2d9 Missing LaTeX template from previous PR 2 years ago
render e56a5c1741 various fixes and updates to new pandoc 10 months ago
template.tex 20d885cf13 template improvements 1 year ago
writedown 63ea651e89 support for source and web target (mkdocs) 1 year ago

README.md

            █               ▗▖
            ▀   ▐▌          ▐▌
█   █ █▟█▌ ██  ▐███  ▟█▙  ▟█▟▌ ▟█▙ █   █▐▙██▖
▜ █ ▛ █▘    █   ▐▌  ▐▙▄▟▌▐▛ ▜▌▐▛ ▜▌▜ █ ▛▐▛ ▐▌
▐▙█▟▌ █     █   ▐▌  ▐▛▀▀▘▐▌ ▐▌▐▌ ▐▌▐▙█▟▌▐▌ ▐▌
▝█ █▘ █   ▗▄█▄▖ ▐▙▄ ▝█▄▄▌▝█▄█▌▝█▄█▘▝█ █▘▐▌ ▐▌
 ▀ ▀  ▀   ▝▀▀▀▘  ▀▀  ▝▀▀  ▝▀▝▘ ▝▀▘  ▀ ▀ ▝▘ ▝▘
        A slick and static academic publisher

INTRODUCTION

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.

software by Dyne.org

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.

REQUIREMENTS

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

BASIC USAGE

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

RENDER FINAL RESULT

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.

SINGLE FILE RENDERING (experimental)

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.

ZOTERO INTEGRATION (experimental)

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

DEVELOPERS

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.

DONATE

Money donations are very welcome and well needed

https://www.dyne.org/donate

LICENSE

Writedown is Copyright (C) 2016-2017 by the Dyne.org Foundation

Writedown is designed, written and maintained by Denis Roio jaromil@dyne.org

Thanks to reviews and contributions by James Barrit jimb@thoughtworks.com

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