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
No comments:
Post a Comment