Small overview on the usage of Org-Mode for blogging leveraging all features that Emacs can give, as an interactive and literate code development environment where you have access to bibliographic tools for easy reference and a comfortable editor.

The whole stack for being able to archive this:

• Debian Linux or any other distribution
• Emacs
• Spacemacs
• Org-More along with other packages (org-ref, org-roam, etc…)
• Python environment (poetry, python and Spacemacs layers)
• Git
• Hugo
• Travis and GitHub

Hugo Structure

Summary

Any text at the beginning of the document is considered a summary until it reaches the max allowed characters or the tag #+hugo: more is found.

Generating color schemes for syntax highlight

hugo gen chromastyles --style=monokoi > themes/strm/static/css/syntax.css

Spacemacs configuration

Layers

Check out the official Org-Mode layer documentation on Spacemacs for further reference. Bellow an example

     (org :variables
          org-enable-epub-support t
          org-enable-org-journal-support t
          org-fontify-whole-heading-line t
          org-fontify-quote-and-verse-blocks t
          org-fontify-done-headline t
          org-pretty-entities t
          org-projectile-file "projectile.org"
          org-projectile-todo-files "todo.org"
          org-journal-dir "~/studies/journal/"
          org-journal-file-format "%Y-%m-%d"
          org-journal-date-prefix "#+TITLE: "
          org-journal-date-format "%A, %B %d %Y"
          org-journal-time-prefix "* "
          org-journal-time-format ""
          org-babel-python-command "python3"
          org-confirm-babel-evaluate nil
          org-use-property-inheritance t
          org-enable-roam-support t
          org-download-image-dir "~/Pictures/org/"
          org-enable-hugo-support t
          )

And append the following to your dotspacemacs-additional-packages to make your life easier.

dotspacemacs-additional-packages '(
                                  ob-async
                                  ob-go
                                  py-autopep8
                                  (py-docformatter :location (recipe :fetcher github :repo "humitos/py-docformatter.el"))
                                  pyimport
                                  org-roam-bibtex
                                  org-noter
                                  org-noter-pdftools
                                  (org-fragtog :location (recipe :fetcher github :repo "io12/org-fragtog"))
                                  )

General Writing tips

Write-room mode will improve your focus by removing everything else from the screen and centering your buffer, use with SPC w C C. More focus can be obtained with org-narrow-to-subtree which will remove everything else from the document except the current sub-tree, there are a few alternatives:

• , s n : org narrow to sub-tree
• SPC n w: widen back to normal
• , ' : open a source code block to be edited on the specialized editor.
• SPC S l : Enable and use langtool

You can use this site to easily convert from markdown to Org-Mode.

Auto Export on save

Auto-export on save can be archived with the following code inside .dir-locals.el on the root folder:

(("content-org/"
  . ((org-mode . ((eval . (org-hugo-auto-export-mode)))))))

Given that some pieces of code may be slow, as for example, training a big neural network or crack some hash, is recommended to add the following header to avoid evaluating code blocks every time that an export is triggered:

#+PROPERTY: header-args :eval never-export

Langtool

Bibtex references

References are handled by org-ref, they are exported from Zotero and Calibre, for papers and books respectively. To make sure that they will be reachable add to the section of the document which you want to have the section bibliography rendered the following piece of text:

bibliography:../../library.bib,../../references.bib

Remember that this is a relative path from your document to the project’s root. After this is done, references can be added with the key combination SPC m i c.

A paper reference will look like this ((Diffie and Hellman 1976)) while a book reference will be rendered like this ((Broedel 2003)).

In case org-ref misbehaves while exporting to HTML, use the following snippet:

(use-package org-ref
  :ensure t
  :init
  (with-eval-after-load 'ox
    (defun my/org-ref-process-buffer--html (backend)
      "Preprocess `org-ref' citations to HTML format.

Do this only if the export backend is `html' or a derivative of
that."
      ;; `ox-hugo' is derived indirectly from `ox-html'.
      ;; ox-hugo <- ox-blackfriday <- ox-md <- ox-html
      (when (org-export-derived-backend-p backend 'html)
        (org-ref-process-buffer 'html)))
    (add-to-list 'org-export-before-parsing-hook #'my/org-ref-process-buffer--html)))

footnotes

Sometimes the text gets too clumsy and some explanations are not required for some reader, but are for others ¹ , to add a footnote use , i f.

Math and LaTeX

LaTeX is rendered using Katex if math variable is set to true on page or site level. On emacs inline LaTeX rendering can be achieved using org-fragtog .

Not all functions are supported, take a look at Katex limitations to check it out before using. Also, if an expression or function is not supported, with Emacs you can directly export the png file which is automatically generated.

Here some inline expression \(a^2=b\) and \( b=2 \), then the solution must be either \[ a=+\sqrt{2} \] or \[ a=-\sqrt{2} \]

Here a multi-line example using Nash Equilibrium to illustrate:

\[ u_i(s_i^*, s_{-i}^*) \geq u_i(s_i, s_{-i}^*) \;\;{\rm for \; all}\;\; s_i \in S_i \]

Literate programming

One of the greatest advantages of using Org-Mode for writing documents is leveraging of literate programming to write a more reproducible research, along with features like Tangle which allows you to extract source from your documents.

Comparing it with alternatives like Jupyter you have all the advantages of your keybindings, I for example use Vim keybindings on Emacs, being able to use several programming environments, references, a brain dump if you use Org-Roam. Along with it, you can start sessions and jump right to it, separate your sessions, so your variables don’t get messed up.

Org files work better with Git in general, so version control is much easier. Emacs supports Jupyter and IPython, but given the power of Org-Mode simply using Python you can archive everything and more.

One thing that is lost is the capability of having inline Plotly plots, which are interactive due to the usage of web technology. But if you are executing Emacs on your desktop you can still use it and plots will open in a browser.

This makes Org-Mode quite superior to any other environment of interactive development and for a local user which can leverage even further of Bibtex, Org-Roam and all babel executors there is no other alternative with such power.

Python and Plots

The given code bellow is a demonstration of the usage of Python.

import seaborn as sns
sns.set_theme(style="ticks")

dots = sns.load_dataset("dots")

# Define the palette as a list to specify exact values
palette = sns.color_palette("rocket_r")

# Plot the lines on two facets
sns.relplot(
    data=dots,
    x="time", y="firing_rate",
    hue="coherence", size="choice", col="align",
    kind="line", size_order=["T1", "T2"], palette=palette,
    height=5, aspect=.75, facet_kws=dict(sharex=False),
).savefig('./demo-plot.png')

If the image above is not displayed in your Emacs use org-toggle-inline-images with the shortcut , T i.

Org Mode tweaks

To avoid re-evaluating the code every time that it is exported, add the following property at the beginning of the document.

#+PROPERTY: header-args :eval never-export

Org Mode examples

Bellow just some random Org-Mode markup to show how it renders.

To buy books would be a good thing if we could also buy the time to read them; but the purchase of books is often mistaken for the assimilation and mastering of their contents. – Arthur Schopenhauer

Some inline styling: Verbatim bold italic

Table rendering:

Example

Including external content

Hugo offers what is called shortcodes, which are mere functions which wrap a more elaborated rendering pipeline of data. Bellow some examples how to include external content using shortcodes.

The shortcodes have to be wrapped around double @@ .. @@, when using a markdown shortcode, include the prefix md: before the actual code.

Twitter

Using the shortcode bellow is possible to render a tweet:

{{< tweet user=“officialmcafee” id=“1405918427663982594” >}}

In a democracy, power is given not taken.

But it is still power.

Love, compassion, caring have no use for it. But it is fuel for greed, hostility,  jealousy...

All power corrupts.

Take care which powers you allow a democracy to wield.

— John McAfee (@officialmcafee) June 18, 2021

Gist

Same applies for a Gist from GitHub:

{{< gist opsxcq f5b3ba08f45d70f998a4cc8a25bf57a3 >}}

YouTube

The inclusion of external videos is also possible

{{< youtube pctYu1Wz514 >}}

Templates

Posts

Studies

Projects

Malware

References