Creating complex tables of contents from markdown - electricbookworks/constitution GitHub Wiki
The Constitution has hundreds of sections, all of which need to be listed in their tables of contents. Creating this contents list manually, with links to each section, would be impossibly time consuming. This hacky little workflow makes it quicker. It may seem clunky and complex at first, but once you get the hang of it, it'll take a couple of minutes at most. (If you know a quicker way to do the same thing, please let me know!)
I'm using Windows, which makes character encoding a nightmare: despite what the forums tell you, don't use Command Prompt or Powershell to concatenate, because they mess up character encoding. You have to install Cygwin (default installation is fine). Then in the Cygwin prompt, navigate to the folder and type:
cat *.md > combined.txt
That says 'concatenate all the files with a .md file extension into one file called combined.txt'. Important: don't use the same file extension (e.g. don't used combined.md) for your input files and output files, or you'll get stuck in a loop, where the file you've created keeps getting combined with itself over and over again.
I paste the markdown into kramdown.herokuapp.com – though for very big files I run that app on my machine using this, because the online version struggles with something as big as the Constitution. At the top of the markdown, though, I add this:
* foo
{:toc}
which tell kramdown to create a table of contents. It'll appear at the top of the resulting HTML, as a list of all the headings in the document with links to those headings.
To do this:
-
In the HTML window in kramdown.herokuapp.com, I right-click the list and select 'Inspect'. (Note I'm using Chrome, and other browsers might have different terms for this stuff.) In the Inspect window that pops up, I look for
<ul id="markdown-toc">. Right-click that and select Edit as HTML. You'll see the whole HTML list, from<ul>to</ul>, in a box. Select it all (Ctrl+A), and copy it (Ctrl+C). -
In a new browser tab, open domchristie.github.io/to-markdown. Paste the HTML list into the left-hand (HTML window). On the right, as if by magic, you'll see a markdown version of your list, complete with links. Copy it (Ctrl+A, Ctrl+C).
Your markdown list has one shortcoming: because it was created from one file, all the links point to IDs in the same document. But your TOC will need to link to those IDs in separate files – in the chapters and schedules of the constitution. So you need to turn something like this:
[Preamble](#preamble)
into something like
[Preamble](0-5-preamble.html#preamble)
thus adding the 0-5-preamble.html.
I do this in a text editor (I use Sublime Text). To move quickly but carefully, I use find-and-replace, replacing each instance of ](#' with, say, ](1.html#(i.e. inserting the1.html). Here I'd place my cursor in front of the first link to 1.html, and quickly click 'Replace' over and over until I've done all of the links to 1.html. Then I'd do the same for 2.html`, and so on. I can get through a couple of hundred links in a couple of minutes.
My markdown TOC is now complete, and I can confidently paste it into my final contents file.