noncog/github-org-mode-hacks

Hacks to format your README written in Emacs' org-mode.

GitHub Org Mode Hacks

Sharing the undocumented things you can do with GitHub, org-mode, and HTML to make a better README.

Why?

The README, is your primary method to portray information about a repository to the reader. GitHub supports using org-mode to create a README, but it’s implementation using org-ruby neither works as claimed nor is complete.

That’s where these hacks come in, primarily using HTML, to get around these limitations, as well as to show some additional possibilities and preferences.

And, I haven’t found anyone talking about these techniques, so I thought I would share them. Please consider submitting yours.

Document Structure

This document covers methods to use org-mode and HTML together. The headings are sorted by the goal we want to achieve.

Table of Contents

• Background
• HTML in Org Documents
• Hiding Org Headings on GitHub
• Centering / Text Alignment
  • Org Syntax
  • Org Tables
  • Code Blocks
• Underlining
• Folding
• Code
  • Inline
  • Block
• Examples
• Hiding Code and Example Blocks
• Tables
• Shields
• Emojis

Background

GitHub uses org-ruby to parse and export an org document as HTML, then it is sanitized using their HTML-pipeline.

These documents allow us to understand what you can and can’t do using org-mode and HTML on GitHub, but that work is summarized for you here.

org-ruby

This software translates org-mode files/syntax directly into HTML. The rules for translation are currently not modifiable. See org-ruby for the default translation list.

The problem with this, is that the translations used by GitHub/org-ruby are incomplete or outdated. Most things you can do with org-mode are supported, but some things are not.

HTML in Org Documents

Please welcome our lord and savior, HTML! This is our primary method to overcome the limitations of org-ruby and Github.

Org-mode supports the use of two syntaxes for writing HTML in a document. The first is inline and the second is block.

Inline

Useful for one-liners.

Syntax:

#+html:

Example:

#+html:<p>Some HTML paragraph</p>

Block

Useful for complex or multi-line HTML.

Syntax:

Example:

<div>
<p>Some longer HTML!</p>
</div>

Hiding Org Headings on GitHub

We can prevent headings from showing up on GitHub using a little known feature of org-ruby.

By including the following at the top of our document, we can use the tag noexport or exclude on headings that we don’t want to show up on GitHub!

#+export_select_tags: export
#+export_exclude_tags: exclude noexport
#+tags: export noexport

This took me way too long to find from here. View the raw file here.

Centering / Text Alignment

This is unfortunately broken in org-ruby, so we use HTML.

The HTML attribute align controls text alignment, including centering.

Syntax:

<div align="center">
Some stuff
</div>

Alignment options:

left
right
center
justify

The centering attribute can be applied to many elements, but I recommend using one of the following elements.

Recommended tags:

<div> <-- Recommended over <p>, as it works more often.
<p>

Example:

#+html:<div align="center">some centered stuff</div>

or

<div align="center">
some centered stuff
</div>

Result:

some centered stuff

Wrapping other tags in these results in them also being centered as well, regardless if they can accept the alignment attribute themselves. You’ll see this in the next sections.

Centering Org Syntax

You can use HTML inline calls to start a center alignment and end it later.

Example:

#+html:<div align="center">
* Org Heading
  Some text.
#+html:</div>

Result:

Org Heading

Some text.

Centering Org Tables

Centering org syntax includes the centering of org-tables.

Example:

#+html:<div align="center">
| org | table |
| foo | bar   |
#+html:</div>

Result:

org	table
foo	bar

Centering Code Blocks

It’s also possible to center the text inside of a code block, not the block itself.

This is useful for posting ASCII art to your README.

Just use the div centering syntax on a code block, like in the previous example.

Syntax:

#+html:<div align="center">
#+begin_src
ASCII Art
#+end_src
#+html:</div>

Example:

 /~~~\/~~\/~~~\/~~~\/~~\/~~~\                    /~~~\/~~\/~~~\/~~~\/~~\/~~~\
 | /\/ /\/ /\ || /\/ /\/ /\ |                    | /\ \/\ \/\ || /\ \/\ \/\ |
 \ \/ /\/ /\/ /\ \/ /\/ /\/ /                    \ \/\ \/\ \/ /\ \/\ \/\ \/ /
  \ \/\ \/\ \/  \ \/\ \/\ \/                      \/ /\/ /\/ /  \/ /\/ /\/ /
,_/\ \/\ \/\ \__/\ \/\ \/\ \______________________/ /\/ /\/ /\__/ /\/ /\/ /\_,
(__/\__/\__/\____/\__/\__/\________________________/\__/\__/\____/\__/\__/\__)

Underlining

Github honors the insert tag for underlining. Even though it’s not specifically for underlining, it gets the job done.

Syntax:

<ins>
</ins>

Example:

#+html:<ins>some underlined text</ins>

or

#+begin_html
<ins>
some underlined text
</ins>
#+end_html

Result:
some underlined text

Folding

This killer feature allows us to hide information in a folded or hidden section.

GitHub honors the summary / details tags for folding sections.

Syntax:

<details>
<summary>The title text or heading of our fold</summary>
<p>Some hidden text</p>
</details>

Example:

<details>
<summary>Hidden Section - Click Me!<summary>
<p>Some hidden text</p>
</details>

Folding Org Syntax

You can also use HTML inline calls to start a fold and end it later. Including folding regular org syntax.

#+html:<details>
#+html:<summary><b>A Hidden Section - Click Me!</b></summary>
* Org Heading
  Some text.
#+html:</details>

Result:

A Hidden Section - Click Me!

Org Heading

Some text.

Code

You can use both HTML and org-mode to generate code blocks. Each have their appropriate use cases.

Inline

Looks like this.

I use these to highlight commands and software where appropriate.

Org-mode

Syntax:

Verbatim:
=SOME INFO= <-- My first choice.

or

Code:
~SOME INFO~ <-- Useful if text inside has an equal sign.

Advantages:

• Useful for quick inline highlighting.
• Text in these strings is not processed for org specific syntax.

Disadvantages:

• Does not always work on Github.
• Cannot use org-mode link syntax to put a link inside of a code block.

HTML

GitHub honors the code tag for inline code blocks.

Syntax:

<code>some text</code>

Example:

#+html:<code>some text</code>

or

<p>This is an inline code with a <code><a href="#html">link</a></code>!</p>

Result:

This is an inline code block with a link!

Advantages:

• More universal.
• Can include links and other formatting inside the code block.

Disadvantages:

• Not quick to use.

Block

GitHub and org-ruby honor the pre tag for code blocks.

Here, org and HTML are very equivalent, except for one disadvantage shown below.

Org-mode

Syntax:

#+begin_src
#+end_src

or

#+begin_example
#+end_example

Example:

#+begin_src
Some code
More code
#+end_src

Result:

Some code
More code

Advantages:

• Quick to write.
• Can write any language, including org-mode syntax. Just prepend an org command with a comma.

Disadvantages:

• Cannot include org-mode links inside inside.

HTML

Syntax:

<pre>some HTML</pre>

Example:

#+html:<pre>Some code or org-syntax: #+begin_src</pre>

or

<pre>
Some code
</pre>

Advantages:

• The inline HTML org syntax can use org syntax in the code block.

Disadvantages:

• Not easy to use.
• To Write HTML inside an HTML code block, you must replace the tag brackets (< >) with &lt; and &gt; (&lt;tag element&gt;).

Examples

I use strictly use org-mode for examples. Here, org-ruby works flawlessly.

Inline

A little known feature is that org has an inline example block.

Any line that begins with a colon (:) followed by a space becomes an example.

Syntax:

: some inline example

Result:

some inline example

Block

This is just a regular org example block. No different from a code block except that it doesn’t have syntax highlighting.

Syntax:

#+begin_example
#+end_example

Hiding Code and Example Blocks

To prevent these from showing up on GitHub simply add :exports none to the #+begin statement for the block.

Tables

Org-ruby translates org tables to HTML just fine, but has some shortcomings.

For regular tables, this is the faster and simpler approach.

If your only table customization goal is to center it, refer to centering org tables above!

For more advanced formatting you may want an HTML table, which allows you to take advantage of aligning and other formatting.

Unfortunately, GitHub does not honor Org’s table alignment syntax when exporting it through org-ruby.

HTML Tables From Org Tables.

Generate your table using org-mode, since it’s quick and easy compared to writing an HTML table, and then export the table using the following technique.

1. Create your org table.
2. Use the command: org-html-export-as-html to export the current org document buffer to an HTML buffer.
3. Copy the HTML table into an HTML block in your org document, replacing the org table.
4. Apply any additional HTML formatting to your table.

Shields

Shields are the little badges found on repositories all over GitHub to quickly and visually share information about the repository.

The only way to put shields in an org document is through HTML.

Here is the most used website to generate shields: shields.io

Just use the URL generated as the source for an image tag.

Syntax:

Without link:
<img src="image_url">

With link:
<a href="hyperlink"><img src="image_url"></a>

Example:

#+html:<a href="https://orgmode.org"><img src="https://img.shields.io/badge/Org-Document-%2377aa99?style=flat-square&logo=org&logoColor=white"></a>

Result:

Tip: I like to center my shields by enclosing it in a paragraph tag with an alignment attribute.

Emojis

1. Find the GitHub emoji you want to use.
2. Use the syntax :emoji_name: anywhere in a text field and the emoji will show up!

Example:

:satisfied:

Result: Here is an emoji: 😆