Scribbler

"Pelican wrapper for scientific note-taking.

Scribbler is a piece of software for managing a notebook from the command line. It was written with scientific note-taking in mind, but could be used for other purposes as well.

The goal was to allow notes to be taken in Markdown, avoiding the need for irritating button pressing when links and images need to be added, with sufficient extensions to make the inclusion of PDF images, LaTeX, BibTeX-style referencing, and various other features possible. Scribbler achieves this by acting as a wrapper for the Pelican static-site generator, for which various additional plugins have been written to give it the desired features. Scribbler also converts the HTML output of Pelican into PDF files which can be printed and placed in a binder along with any hand-written notes.

By default notes are written in Markdown, although they may also be written in reStructuredText or HTML. As Scribbler is just a wrapper for Pelican, it is strongly recommended that you read its documentation on writing content. Note that what they refer to as "articles" are equivalent to notes and what they refer to as "pages" are equivalent to appendices. The Pelican syntax for internal links will work with Scribbler, although Scribbler's directory structure is a little different. Whereas the root of the directory structure seen by Pelican is the content directory, for Scribbler it is the top level of the notebook's directory. However, links will only be generated to the contents of the notes, appendices, and files folders.

In addition to standard Markdown, various plugins are loaded providing extra functionality. Of particular note is Markdown Extra, which provides syntax for such things as footnotes, tables, and more. CodeHilite provides syntax-highlighting for code-snippets, as described in the Pelican documentation. figureAltCaption will convert each image which stands in its own paragraph into a <figure> element, with the alt-text used as a caption.

Additionally, several Pelican plugins are used to provide further functionality. These plugins can be used with reStructuredText and HTML content as well as Markdown.

render_math provides support for LaTeX equations. In Markdown, inline math appears between dollar signs. However, there must be now white spacce before the ending $ (i.e. $x^2$ will render, but $ x^2 $ will not). Math appearing on its own line should use double dollar-signs ($$). \begin{equation} and \end{equation} can also be used and the equation can be labelled and referenced, as in actual LaTeX. Note that this depends on MathJax to work and will only render if there is an internet connection.

The pdf-img plugin, which I wrote specifically for Scribbler, allows PDF, PS, and EPS graphics to be used as the source for images. This plugin will simply scan through all images in each note and appendix. If it ends with the extension pdf, ps, or eps then it will create a PNG thumbnail of the first page of the document. This thumbnail will be inserted as the image source, while the image itself will act as a link to the original PDF/PS/EPS file.

My figure-ref plugin (also written for Scribbler) will look for any figures in the HTML output whose caption begins with the format labelname ::. This will be replaced by a figure number. Any references to {#labelname} in the rest of the note will also be replaced with the correct figure number.

Finally, pelican-cite allows BibTeX-style referencing within your notes. If a bibfile is specified in your notebook settings then it will be used as a database of bibliographic data. This file may, optionally be provided or overridden on a per-note basis by adding the metadata publications_src. Inline references can then be provided with the syntax [@bibtexkey] (for author names with year in parentheses) or [@@bibtexkey] (for author names and year all in parentheses). The inline citation will act as a link to a full bibliography entry at the end of the note."

https://github.com/cmacmackin/scribbler