A Service for creating Marked indexes

In case you’re not familiar with it already, Marked has the ability to include external documents within any other document. The main use for this is creating longer documents with chapters/sections split into separate files. Then you create an index file that pulls them all together in the proper order.

In testing some tweaks to this feature, I had a need to be able to quickly generate index files from a folder or selection of files. This Service is my solution for the problem.

The “Create Marked Index” Service

This Service allows you to take a Finder selection of multiple files and/or folders and generate an “index.md” file at the root of the selection that contains all of the files and sub-folder files wrapped in (up to three levels deep) Marked’s include syntax. It will use the proper syntax for code files (to insert them as highlighted code blocks), recognize any type of text file, and ignore files you won’t want in the index (images, rich text files, bundles, etc.).

The included files are ordered alphanumerically in the index, so you can specify the order by prefixing filenames with a number, or just edit the generated index to move included files around.

Converting an existing index file to Marked format

If only one file is selected when the service runs, the content of that file will be read as a list of files to convert to Marked’s format. This works well with Leanpub and mmd_merge files, and with any plain text list of filenames. The files listed must actually exist in the folder of the index file to be converted, but they can have relative paths from that file.

Installing the Service

To install it, just download the zip file below, open it and double click the Service. This will ask you if you want to install it, which you should confirm. Now, when you have a file/folder selection in Finder (or other file management application), you can right click and select “Create Marked Index.” It will generate the “index.md” file and reveal it in Finder upon completion. Double click the index file to edit and finalize the order.

Command line usage

You can also use the script from this Service as a command line tool. The source is available as a Gist that you can save to your local drive as “marked_index.rb”. Make the file executable by running chmod a+x marked_index.rb.

The script takes input in two forms. First, you can pass it a list of filenames as arguments, e.g. marked_index.rb file1.md file2.md file3.md. If any of the arguments are directories, they will be searched for more text/code files which will also be included.

The second form of input is STDIN, meaning you can pipe the output of a command to it. This allows you to do two things: use commands like ls and find to build the index, and convert other index formats (like Leanpub or mmd_merge) into Marked include files. Note that Marked can already read Leanpub and mmd_merge files, but neither format allows you to add additional Markdown content in the index, which Marked’s format does. Here’s a simple example:

ls --color=never -1|marked_index.rb

This will generate an index.md file in the current directory that includes all the Markdown/code files in the current folder and any subfolders (up to three levels deep). Or, create the index using only Markdown files and ignore any other files in the folder:

find . -name "*.md"|marked_index.rb

To convert a Leanpub file to Marked syntax, you would just use:

marked_index.rb Book.txt

Hopefully this will speed up writing and conversion processes for other people as well. If this sounds interesting but you don’t have Marked 2 yet, grab a free trial at marked2app.com.

I’ll be posting a video (once I get my voice back) showing more tricks for working with multi-file documents in Marked, including how to tell which parts of the document came from which file while you’re previewing (hint: type Command-Control-B or hit Shift-I).

Download

Updated: 2.2 will now increment the filename rather than overwriting previous index.md files.