--- title: Layouts and Templates blurb: Learn the details about how templates and layouts work with each other as well as some best practices for their use. layout: template-logo-medium --- <%= md_links %> <%= md_images %> <%= current_page.data.title %> ============================== <%= current_page.data.blurb %> _Middlemac_ decouples your help _content_ from the display and final document structure by taking advantage of layouts and templates. In general both layouts and templates do the same thing; they wrap your content into the structure required of an HTML file. In practice, though, _Middlemac_ distinguishes between them in the manner: a _layout_ defines the formal HTML structure of the end document, and a template defines the superficial appearance of a particular page. For example a page might be wrapped in the `template-logo-medium` template to define its overall look, and then further wrapped in `layout-html4` to ensure that it has the required structure for an Apple help book. Templates --------- _Middlemac_ comes with three templates inspired by recent Mac OS X help files. Although you can certainly use any of the templates you desire (or create your own), the included templates were designed with specific purposes in mind. `template-logo-large` : This template features your help icon in a large size with your target’s `ProductName` and `ProductURI` below it, in a left frame-like area. Your content is in the right frame-like area. This template was designed to be suited for the main landing page and for main section landing pages consisting primarily of links and descriptions of other pages. `template-logo-medium` : This template places a smaller logo in a frame-like area to the right, followed by automatically placed “related links” to other pages in the same group. Your content will occupy the large, left side of the window. This template is idea for multiple, related pages within a group. `template-logo-small` : The template places a very small logo at the top of your page. Related links will appear at the bottom of the page after your content. This template is most suited for topics that stand somewhat alone. Each of these templates will wrap a layout around them. By default they will always use `layout-html4`, although you can force _Middlemac_ to use the `layout-xhtml` template with the `:xhtml` frontmatter key. You should never do this, though, as Apple requires your content -- except the top level landing page -- to be HTML4. Layouts ------- `layout-html4` : This is just an HTML 4.01 wrapper template and if you follow all of the conventions there's nothing you should have to change here. `layout-xhtml` : Apple's help landing page (the main page) is supposed to be an XHTML 1.0 Strict document. If you follow all of the conventions there's nothing you should have to change here.