NOTE: I'm no longer working on this, having moved to Org Mode in Emacs.
Go from a single Markdown source file to well-presented documents like this. Octavo is a wrapper for the excellent pandoc.
If you're producing finished-product documents like PDFs or HTML from a text source such as Markdown, you'll need two things: (a) a way of crafting your Markdown files to exploit certain features like highlight boxes and including external text snippets, and (b) nice templates that take advantage of these features. Octavo supplies the (a) and (b).
Why does it exist? As a psychology lecturer, I wanted a way to write statistics workshop booklets in Markdown (without all that tedious mucking around in Latex) and have my computer produce multiple versions, insert commonly-used text, as well as do the usual stuff like produce a References section in APA style. And handle equations. I also wanted it to last for several years, if not decades. I did the former. We'll see about the latter.
This tool has been developed on macOS (Yosemite) but should be easily portable to other UNIX-like operating systems such as Linux. I'm very happy to accept pull requests.
Octavo is a tool for multiple document deployment.
-
Use templates for specific readers (large text, dark background, etc.)
-
Produce any document type (PDF, HTML, .Docx, spoken word etc.) using the excellent pandoc. Octavo can upload all versions to web server and insert smart text in all documents with appropriate hyperlinks, like this:
- You can mark sections as redactable, then set a Yaml field in the Markdown file telling Octavo either show redacted content or hide it. Like this:
redact: false
- Include text from other files, like:
<include>licence</include>
- Put text in boxes. Because my usage is for students, I've got 'task', 'journal' and 'highlight'. Like this:
<task>
Run the analysis
</task>
- Latex equations are supported without a problem; as are standard citations. In this example, the equation is Cohen's D, which is described by the part between $$ and $$; the part in curly brackets will label this as an equation (you then provide lists of equations; or tables, or figures):
$$ d=\frac{\bar{x}{1}-\bar{x}{2}}{s} $$ {#eq:cohensD}
Which gets you:
-
Install the dependencies (see below)
-
Download the above files (either individually or by cloning this repository)
Install, if you haven't already, a full LaTeX distribution, the Haskell platform, Cabal, and install Pandoc using Cabal. Also via Cabal, install Pandoc filters pandoc-csv2table, pandoc-crossref, pandoc-citeproc. Finally, install Python3-pip and use pip3, which you've just installed, to itself install pandocfilters.
Notes:
-
The above installation works for macOS Yosemite and Ubuntu 16.04.2
-
LaTeX and Haskell (and Cabal) are huge
-
On Ubuntu, I had a persistent Cabal installation fail that I managed to fix with the following advice
octavo.sh -f <file> [-c <file>] [-ybvdhn]
-f --file [arg] Markdown file to process. Required.
-b --bash Print Bash variables to standard output
-c --config [arg] Specify a configuration Yaml file. Default is .octavoConfig.yml in the script directory.
-d --debug Enables debug mode
-n --no-color Disable color output
-o --output Print processed Markdown
-p --pandocverbose Verbose Pandoc output to standard output
-u --dummy Dummy run
-v --verbose Enable verbose mode; print script as it is executed
-y --yaml Print Yaml of Markdown file to standard output
-h --help This page
Your Markdown file should have a wodge of YAML at the top that follows the example in the examples folder. Have a look at each setting and tweak to suit your needs. These YAML settings will be applied to document in which it is found.
-
.octavoConfig.yml: Contains global preferences and information about templates
-
/templates/documentDefault.yml: Common document properties that you might want to include in your Yaml header.
-
octivate.markdown: A minimal working example Yaml header.
-
filters: Pandoc filters, modified for use with Octavo. They are named in .octavoConfig.yml
-
includes: Octavo will look here for text you wish to include dynamically. Use filename to do this.
-
media: Graphics to be used, such as header images.
-
sandbox: Here you'll find an advanced document called 1art.markdown, which uses several Octavo features.
-
templates: Octavo-styled Pandoc templates.
If you use Vim like me, you might find the following useful. Note that I'm launching Octavo on the current document using a plugin called asyncrun, which permits it to run in the background.
Use :Octavo to run Octavo on the current document:
command Octavo AsyncRun ! octavo.sh -f %
Use :OctavoDebug to do the same, but with debug mode on:
command OctavoDebugMode AsyncRun ! octavo.sh -f % -d
For quick access, map your leader key and 'o' to launch Octavo:
noremap <leader>o :Octavo<CR> " leader-O launches Octavo
Use :Octivate to add minimal Yaml to the top of your file, just enough to create a minimal Octavo document (note that you'll need to replace '~/Dropbox/Scripts/octavo' with the correct path to your Octavo directory):
command Octivate 0r ~/Dropbox/Scripts/octavo/octivate.markdown
- Create a installer for Homebrew
Thanks to John Gruber for creating Markdown and John MacFarlane for creating Pandoc, as well as the authors of the other bits and pieces that Octavo depends upon.
Happy to look at any contributions, particularly for Latex templates.
### Version 1.1
Uses SFTP instead of FTP, so public key encryption now required.
Refactored.
Support nicer tags like <task></task> to denote tasks.
Add support for Microsoft Word .docx format.
Fix a bug where entire Deploy directory was uploaded with each FTP operation. Now only new files are uploaded. Significant speed increase.
Initial release.