[TxMt] New Bundle: Markdown2Book

[Soryu]

Good Morning :)


I put together and polished some commands Allan made in order to get  
the TextMate Documentation under way. As I worked on a documentation  
project at the same time, I used his scripts, bundled them and  
adapted them a little to my needs. If you are curious as to what  
happens behind the scenes… Here it goes.

This bundle is for compiling a Documentation project made of several  
Markdown files to HTML. It generates a TOC, a print version with all  
chapters on one page and HTML files for each chapter. You can use  
references to easily link between your pages.

I appended the bundle “Markdown2Book” plus, as an example how to use  
it, the first three chapters of the TextMate manual.


Have fun,
Soryu.


PS: For quick reference the Help file from the bundle (also available  
from the bundle itself via the “Readme” command):

# Setup

You will need a TextMate Project (a Scratch Project will do) to make  
this work.

## Structure

The following files & folders are needed:

* `pages`

     This is where all your markdown files go. You need to make a new  
file for each chapter. It should have one first level heading which  
will be used for the name of the chapter (in the Table of Contents,  
for the Navigational Links & in the HTML title).
     The files in the `pages` directory are converted to HTML (using  
Markdown and SmartyPants) with the _Generate_ Command. They have to  
be in the right order, so they have to be named beginning with  
numbers followed by a space or an underscore (as seen in the included  
example). This prefix will be stripped by the Generate Script.

* `html`

     The generated files will go here.

     * `index.html`: Table of Contents from which you can navigate to  
all chapter.
     * `all_pages.html`: A single files with all chapters. This is  
mainly for printing and it uses the `print.css` Stylesheet.
     * `*.html`: Every chapter has it's own file.

     Also this folder holds two links to the css and images folder.  
When "deploying" your compiled book, just replace these by the actual  
folders.


* `templates`

     This folder contains three html templates. Adapt them to your  
needs.

     * `all.rhtml`: template for the `all_pages.html` file which  
contains all your chapters.
     * `chapter.html`: template for each chapter
     * `toc.html`: template for the `index.html` file containing the  
Table of Contents

* `css`

     This folder contains the stylesheets (`stylesheet.css` and  
`print.css`). Adapt those as you like. The default style resembles  
the [TextMate Manual](http://macromates.com/textmate/manual/).

* `images`

     This folder should hold all your images. When the book is  
generated `height` and `width` HTML attributes are added to the  
images. The source path could be changed, too, to make it absolute.



## References

You can use reference style links (`[link description][link id]`) in  
your text. There is a command _Update References_ that will collect  
them from all `.markdown` files in the `pages` folder and write them  
to a file `markdown.references` in the project root. It notifies you  
of missing or duplicate entries via a Tooltip. You can then edit this  
file and insert the link targets within your text. The _Generate_  
Script will add `id` attributes to your headings, so you can  
reference them directly. Is converts some characters (`- \/_`) to  
underscores and strips non-alphanumeric characters afterwards.

I wrote a command _Show References_ that brings up a dialog with all  
the references from the `markdown.references` file and inserts a  
reference snippet.

## Generation process

The _Generate_ Command is a Ruby Script, which does some  
transformation, constructs the Table of Contents and runs all your  
Markdown files through [Markdown](http://daringfireball.net/projects/ 
markdown/), [SmartyPants](http://daringfireball.net/projects/ 
smartypants/) (for good Typography) and the Image-Script.

<hr />

 > Credits to Allan for writing the initial version of all this. I,  
Soryu, bundled it up in a TextMate bundle and added/polished some stuff.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: Markdown2Book.tmbundle.zip
Type: application/zip
Size: 8199 bytes
Desc: not available
URL: <http://lists.macromates.com/textmate/attachments/20060201/26a071e6/attachment.zip>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: manual.zip
Type: application/zip
Size: 41674 bytes
Desc: not available
URL: <http://lists.macromates.com/textmate/attachments/20060201/26a071e6/attachment-0001.zip>
-------------- next part --------------