one-ox | src-block

Table of content

Code highlighting with htmlize

Description

one-ox highlights code via the function one-ox-htmlize that uses htmlize to do the work.

For a given piece of code X in a certain language Y, X will be highlighted as it would be in the emacs mode Z used to edit Y code.

For instance, clojure-mode is used to highlight Clojure code and sh-mode is used to highlight Bash code.

Attributes of a face (like background-color or foreground-color) are not taken directly. A generated name for the face is produced and used as the CSS class for the parts of the code X that are highlighted with that face.

For instance, in sh-mode, the word echo is highlighted with the face font-lock-builtin-face. So, the word echo in a piece of Shell (or Bash) code will be transformed into: 

<span class="one-hl-builtin">echo</span>

The whole piece of code X, once the previously described operations have been done, is wrapped:

  1. for a normal block with the component: 

    <pre><code class="one-hl one-hl-block">...</code></pre>

  2. for a result block with the component: 

    <pre><code class="one-hl one-hl-results">...</code></pre>

    See section org keyword RESULTS.

Example with Bash code

For instance, the following org src-block, containing some bash code: 

#+BEGIN_SRC bash
echo "list file's extensions in current dir:"
for f in `ls`; do
    echo ${f##*.}
done
#+END_SRC

is exported as follow: 

<pre><code class="one-hl one-hl-block"><span class="one-hl-builtin">echo</span> <span class="one-hl-string">"list file's extensions in current dir:"</span>
<span class="one-hl-keyword">for</span> f<span class="one-hl-keyword"> in</span> <span class="one-hl-sh-quoted-exec">`ls`</span>; <span class="one-hl-keyword">do</span>
    <span class="one-hl-builtin">echo</span> ${<span class="one-hl-variable-name">f</span>##*.}
<span class="one-hl-keyword">done</span></code></pre>
</div>

and rendered like this: 

echo "list file's extensions in current dir:"
for f in `ls`; do
    echo ${f##*.}
done

Note that one-ox-htmlize has produced and used the following CSS classes (listed with their corresponding emacs faces): 

# from font-lock
one-hl-builtin        --> font-lock-builtin-face
one-hl-keyword        --> font-lock-keyword-face
one-hl-string         --> font-lock-string-face
one-hl-variable-name  --> font-lock-variable-name-face

# specific to sh-mode
one-hl-sh-quoted-exec --> sh-quoted-exec

You might have notice the pattern used for font-lock faces and the one used for mode specific faces.

one.el provides a default style sheet (one-default-css) that has the CSS classes defined for all the font-lock faces (faces starting by font-lock-) but not the specific faces used by each prog mode.

You can add the CSS classes specific to the prog modes you use as you go and need them.

Org keyword RESULTS

Result blocks are preceded by a line starting with #+RESULTS:. Blocks that are not result blocks are normal blocks.

When exported, normal blocks and result blocks differ only by their CSS classes:

  • one-hl one-hl-block for normal blocks,

  • one-hl one-hl-results for result blocks.

This way result blocks can be rendered with a different style than normal blocks as we can see in the following example.

Example using org keyword 'RESULTS'

The following org snippet: 

#+BEGIN_SRC bash :results output
ls
#+END_SRC

#+RESULTS:
: assets
: docs.org
: public

is exported by one-ox as follow: 

<pre><code class="one-hl one-hl-block">ls</code></pre>
<pre><code class="one-hl one-hl-results">assets
docs.org
public</code></pre>

and is rendered by one-ox with the first block (normal block) having a different style from second block (result block): 

ls
assets
docs.org
public

Code blocks inside list

Lists can contain source blocks as we can see in the following org snippet 

1. item 1

   #+BEGIN_SRC emacs-lisp
   (message "src-block in item 1")
   #+END_SRC

2. item 2
3. item 3

which is exported by one as follow 

<ol>
  <li>
    <p>item 1</p>
    <pre><code class="one-hl one-hl-block">(message <span class="one-hl-string">"src-block in item 1"</span>)</code></pre>
  </li>
  <li><p>item 2</p></li>
  <li><p>item 3</p></li>
</ol>

and is rendered by one-ox like this:

  1. item 1 

    (message "src-block in item 1")

  2. item 2

  3. item 3

PREVRANDOMNEXT