--- title: File Types blurb: Middleman uses several filetypes to get its job done. An understanding of their differences is important to your successful use of Middlemac. layout: template-logo-medium --- <%= md_links %> <%= md_images %> <%= current_page.data.title %> ============================== <%= current_page.data.blurb %> Although you can use static `.html` files to build your help book, you would be sacrificing a lot of _Middleman_’s utility to do so, because static html is simply copied to your build directory as-is, with no opportunity to take advantages of the infrastructure that _Middleman_ and _Middlemac_ offer you. Instead you will probably chose a combination of `.haml`, `.md`, and `.erb` files, and even combinations of them in a single file! Filetype extensions ------------------- As distributed, _Middleman_ (and thus _Middlemac_) understand several file type extensions and will process them accordingly. `.html` : HTML files are regarded as already processed, and they will be copied verbatim to the build directory. `.erb` : Embedded Ruby files are files that contain Ruby code embedded in them. This is useful for including simple if/else logic and including partials and using helpers. Ruby code is delimited within `<%% %>` (generates no output) or `<%%= %>` (does generate output) tags. For example, `<%%= "Hello, #{name}! %>` outputs a string into a generated HTML document, and you will encounter several more examples within this documentation. `.haml` : The “HTML abstraction markup language” excels at enforcing structure in your HTML-target documents, and is clutter-free and easy to read. It supports many built-in filters for including content in Ruby, Markdown, raw source code, and more. _Middlemac_’s templates, layouts, and partials are written in HAML. You can learn more about HAML on [its website](http://haml.info/). `.md` : Markdown is a plain-text formatting syntax that is exceedingly easy to read and write in its source form, and mostly internally logically consistent. _Middlemac_ uses [kramdown](http://kramdown.gettalong.org/) as its text-to-HTML engine, and offers several useful features not found in plain vanilla Markdown. `.scss` : “Sassy” CSS files use SASS markup and render into standard `.css` files. You can use SASS as you see fit; it’s fully compatible with CSS, and all CSS is valid SCSS. Why “SASS” and “SCSS”? SASS is the name of the project as well as an older, non-CSS compatible format. So, SASS is the project, and SCSS is the file format. You can learn more about SASS on [its website](http://sass-lang.com/). Files with a leading underscore ------------------------------- Regardless of the file type, files with a leading underscore (“\_”) will be processed by _Middleman_ (if it’s a type that _Middleman_ recognizes), but _will not_ be copied to your build directory. An example of this type of file is a partial, which we want _Middleman_ to process and make ready for use, but which we don’t want copied to the output directory because its content will be included in other files that need it. Filetype chaining ----------------- _This_ is what’s cool about the _Middleman_ build system: files are chained and processed multiple times by multiple processing systems, with the end result of producing the final file format. What does this mean? Let’s look at this example: `hello_world.html.erb` Middleman will produce a file (that’s then copied to the build output) named `hello_world.html` after processing it as an `.erb` file. For example: ~~~~ erb

<%%= hello_world_function %>

~~~~ Will produce a `hello_world.html` file containing this (assuming that `hello_world_function` exists): ~~~~ erb

Hello, world!

~~~~ What if we try this? `hello_world.html.md.erb` ~~~~ markdown # Introduction <%%= hello_world_function %> ~~~~ Accounting for removing all of the HTML head section, etc., we end up with: ~~~~ html

Introduction

Hello, world!

~~~~ It’s important to understand that file type chaining works from right to left. The last extension is processed first, then the penultimate extension, then the antepenultimate extension, etc. If you try to use a file named `hello_world.html.erb.md` then the results will be unexpected. Markdown will encounter `<%% %>` tag-sets and attempt to render them in HTML. When the ERB processor is passed the file, it will no longer encounter the tag-sets with the embedded Ruby. HAML rarely needs to be chained ------------------------------- HAML includes filters and support for Ruby directly, and so it rarely needs to be chained. For example: ~~~~ haml %h1 Introduction %p= hello_world_function - if true == true %p Well, duh. %p :markdown _Today_a computer told me “Hello, world.” It was **only** addressing me, and so I don’t know why it addressed me as the whole world. ~~~~ The use of `=` in the `%p=` tag is a flag that indicates HAML should be expecting Ruby code. Likewise, the solitary `-` indicates Ruby code and will not generate output. The use of `:markdown` indicates that Markdown-formatted text will be used. This might make you think that HAML is a Swiss Army knife, and why bother with other filetypes? Test it: once you’re familiar with the all of the basics, try coming back to this page’s source and convert if from `.html.md.erb` to `.html.haml`, and then choose whichever works for you.