Notes on org-mode
Table of Contents
1 Overview
I use org-mode instead of regular markdown, because org-mode does more organizational,
outlining, mindmapping -type stuff and it also happens to have some nice export/transformation
capabilities.
This is a super-terse explainer I used to put at the bottom of all my org-mode files, but have since decided not to, since it's just bloat for each and every org-mode file.
2 Org-mode explainer
Text markup. More stars means lower-level items. Blank lines between paragraphs. Indentation
doesn't matter (except for lists). bold italic code verbatim (probably should use verbatim instead of code). Internal link. (You can also do it by just pointing to a section title,
as is done below in one instance, but if you do, then changing the section title becomes a
problem.) Link to Google (although just pasting in a URL works fine, too (see "more info",
below)).
Subscript: H2O (depending on the options at the top of the file, don't paste in code_with_underscores w/out surrounding it with ='s). (Superscript: E = mc2.)
one-line code sample ok, maybe two lines
Multi-line example like maybe a pasted email or something you don't want line-wrapping or other /character interpretation/ applied to
Bullet lists:
- one
- two
- sub-item (indentation matters here)
Definitions:
- terms
- Can be defined
Checklists:
[ ]Items can be…[X]…checked off[-]And (dash means "partially completed")[X]you can have sublists[ ]if you really want to
More info:
- More info than you ever cared for: https://orgmode.org
- If you truly want to go down the rabbit hole: https://melpa.org/#/?q=org-mode
2.1 Maintaining this file without emacs
If you want to update the contents of this file and you're not an emacs user (i.e., you're a normal person), you might be able to use pandoc (https://pandoc.org/) to render this text file to whatever format you like.
See On processing this file with Pandoc.
(You might also be able to do it by installing emacs and using it as a command-line processor, but I haven't figured that out quite yet.)
Alternatively, you can just DELETE the generated HTML file (including in any repositories where it exists) and update this text file without attempting to regenerate the HTML. In the end, it's just text.
3 On processing this file with Pandoc
There is a program, pandoc (https://pandoc.org/), which can be used to turn this org-mode file into whatever you
want.
If you do use Pandoc, try the following command line:
pandoc --from=org --to=html5 --standalone --table-of-contents --toc-depth=6 --variable=secnumdepth:6 --number-sections --include-in-header=pandoc-header-extra.html --output=<output-html-file> <this-file>