Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/davejacobs/mint

Word processing for people who love the commandline
https://github.com/davejacobs/mint

commandline publishing ruby stylesheets

Last synced: about 1 month ago
JSON representation

Word processing for people who love the commandline

Awesome Lists containing this project

README 

        
# What is Mint?



Mint transforms your plain text documents into beautiful documents. It makes the process simple but customizable.



Why would you want to keep all of your documents as plain text?



- To focus on words and structure when you write

- To control style with a single command, independently of document structure

- To keep your text and formatting under version control

- To make your text amenable to scripting--for example, text analysis



What does Mint create from these source files? Beautiful, styled HTML ready to print, e-mail, export, and present.



In a few words: *Mint processes words so you don't have to.*



## The mint command



If you have a plain text document formatted in Markdown or Textile or almost any other templating language, you're ready to go.



The easiest Mint command doesn't require configuration. It transforms a document into HTML and links it to the default stylesheet, which I've designed for you.



Simply type:



    mint publish Minimalism.md



And voilà, Minimalism.html will show up next to Minimalism.md.



Opening Minimalism.html with your favorite web browser--[Firefox is best for typography][Firefox typography], but Webkit-based browsers (Chrome, Safari) work, too--will show what looks like a word-processed document, complete with big bold headers, italic emphasis, automatically indented and numbered lists, and bullets. If you're in a modern browser, you'll even see ligatures and proper kerning. The page will be on a white canvas that looks like a page, even though you are in a browser.



Sending that page to a printer is as easy as clicking "Print" from your browser. What comes out of your printer will have a 12 pt base font, normal margins, and a not-too-cramped baseline. (Ah the wonder of print stylesheets.)



You can throw as many files as you'd like in. Any commandline argument *not* preceded by an option (e.g., `--template`) or in the `mint` command vocabulary (more on that in a minute) will be interpreted as a file name:



    mint publish Minimalism.md Proposal.md Protocol.md



This command can be tweaked with options and arguments to be more flexible:



    mint publish Minimalism.md --template resume  # specifies a style template

    mint publish Minimalism.md --destination final --style-destination=styles



For a listing of mint options, take [a look at the tutorial][tutorial] or the [full API](http://www.rubydoc.info/github/davejacobs/mint).



## A basic Mint document



Mint is loaded with smart defaults, so if you don't want to configure something--say, the basic HTML skeleton of your document or the output directory--you don't have to. You'll probably be surprised at how easy it is to use out of the box, and how configurable it is.



    document = Mint::Document.new "Minimalism.md"

    document.publish!



If you want to customize your document, though--and that's why I built this library--Mint makes that easy.



To understand Mint's flexibility, you'll want to [take a look at the API][API].



[Firefox typography]: http://opentype.info/blog/2008/06/14/kerning-and-opentype-features-in-firefox-3/ "Firefox 3 supports kerning and automatic ligatures"



## Templates



Templates can be written in any format accepted by the Tilt template interface library. (See [the Tilt TEMPLATES file][Tilt templates] for more information.)



In a template layouts, Ruby calls are sparse but necessary.



If you're designing a layout, you need to indicate where Mint should place your content. For that simple reason, raw HTML files cannot be layouts. Instead, if you want to use HTML templates, you should use the ERB format. These files are essentially HTML with the possibility for Ruby calls. You can even use the .html extension for your files. Just code the dynamic portion using ERB syntax.



Inside your template, use the `content` method to place your source's content.



You will want to point to your document's stylesheet (via a relative URL) from within your layout, usually in the `