{"_id":"blacksmith","_rev":"58-5a97aed509e4ac19b0815c36a689158a","name":"blacksmith","description":"A static site generator built with Node.js, Plates, and Marked.","dist-tags":{"latest":"1.1.3","stable":"1.1.3"},"versions":{"0.0.7":{"name":"blacksmith","description":"The node documentation project","version":"0.0.7","scripts":{"start":"bin/server"},"bin":{"blacksmith":"bin/blacksmith"},"author":{"name":"Nodejitsu","email":"info@nodejitsu.com"},"dependencies":{"blacksmith-sites":"0.0.1","async":"0.1.x","marked":"git+https://github.com/chjj/marked.git#gfm","traverse":"0.4.x","mkdirp":"0.0.x","http-server":"0.2.4","jsdom":"0.2.x","weld":"0.2.1","findit":"0.1.x","flatiron":"0.1.5-1","nconf":"0.4.3","ncp":"0.2.x","colors":"*","optimist":"0.2.x","wordwrap":"0.0.x","rss":"0.0.x","hashish":"0.0.x","prompt":"0.1.x","winston":"0.5.x","cliff":"0.1.x","utile":"0.0.10","alists":"*"},"_npmUser":{"name":"mmalecki","email":"maciej.malecki@notimplemented.org"},"_id":"blacksmith@0.0.7","devDependencies":{},"engines":{"node":"*"},"_engineSupported":true,"_npmVersion":"1.1.0-beta-4","_nodeVersion":"v0.7.0-pre","_defaultsLoaded":true,"dist":{"shasum":"87820ecb5645c9655916ff791dd8d31be44934db","tarball":"https://registry.npmjs.org/blacksmith/-/blacksmith-0.0.7.tgz","integrity":"sha512-oXSaJ+g5kOW6eY+/MOLRi+hpKjAcovFwbzcl3eg2IGzebGqKlZWUK8UW2O2uuFP/FifgyD66K/+VYtnjChsTUA==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIFQO9LFOPlcLJKDQ3JKU1XpjjzGcBGiuU+j5BK5u2E+yAiEAriil4e+hfZez1HvHGBWs0W1Gt5q/ZPm9F/sRj4YWClk="}]},"maintainers":[{"name":"mmalecki","email":"maciej.malecki@notimplemented.org"}],"directories":{}},"0.0.8":{"name":"blacksmith","description":"The node documentation project","version":"0.0.8","scripts":{"start":"bin/server"},"bin":{"blacksmith":"bin/blacksmith"},"author":{"name":"Nodejitsu","email":"info@nodejitsu.com"},"dependencies":{"blacksmith-sites":"0.0.x","async":"0.1.x","marked":"git+https://github.com/chjj/marked.git#gfm","traverse":"0.4.x","mkdirp":"0.0.x","http-server":"0.2.4","jsdom":"0.2.x","weld":"0.2.1","findit":"0.1.x","flatiron":"0.1.5-1","nconf":"0.4.3","ncp":"0.2.x","colors":"*","optimist":"0.2.x","wordwrap":"0.0.x","rss":"0.0.x","hashish":"0.0.x","prompt":"0.1.x","winston":"0.5.x","cliff":"0.1.x","utile":"0.0.10","alists":"*"},"_npmUser":{"name":"mmalecki","email":"maciej.malecki@notimplemented.org"},"_id":"blacksmith@0.0.8","devDependencies":{},"engines":{"node":"*"},"_engineSupported":true,"_npmVersion":"1.1.0-beta-4","_nodeVersion":"v0.7.0-pre","_defaultsLoaded":true,"dist":{"shasum":"c12f669c52a7f8c9f65663494c1737eeff4c8938","tarball":"https://registry.npmjs.org/blacksmith/-/blacksmith-0.0.8.tgz","integrity":"sha512-JGp7eSHGN0BAixdU/1LADSstorpYXHz/FrR2Xk8J7mPw8W+ZVjPVIf7zXuUWJd92bSkulWED3tf2wWT7no74Hw==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIHufpUCN6o/4+3EaWZ204n5CTT7LmK6qNpVLHVHspSUkAiA2nQNkuPPhlUWD7ViRm+/QFMrDRYp4Sib6eLZGoTo50Q=="}]},"maintainers":[{"name":"mmalecki","email":"maciej.malecki@notimplemented.org"}],"directories":{}},"0.0.9":{"name":"blacksmith","description":"The node documentation project","version":"0.0.9","scripts":{"start":"bin/server"},"bin":{"blacksmith":"bin/blacksmith"},"author":{"name":"Nodejitsu","email":"info@nodejitsu.com"},"dependencies":{"blacksmith-sites":"0.0.x","async":"0.1.x","marked":"0.1.x","traverse":"0.4.x","mkdirp":"0.0.x","http-server":"0.2.4","jsdom":"0.2.x","weld":"0.2.1","findit":"0.1.x","flatiron":"0.1.5-1","nconf":"0.4.3","ncp":"0.2.x","colors":"*","optimist":"0.2.x","wordwrap":"0.0.x","rss":"0.0.x","hashish":"0.0.x","prompt":"0.1.x","winston":"0.5.x","cliff":"0.1.x","utile":"0.0.10","alists":"*"},"_npmUser":{"name":"jesusabdullah","email":"josh.holbrook@gmail.com"},"_id":"blacksmith@0.0.9","devDependencies":{},"optionalDependencies":{},"engines":{"node":"*"},"_engineSupported":true,"_npmVersion":"1.1.0-3","_nodeVersion":"v0.6.6","_defaultsLoaded":true,"dist":{"shasum":"9c13283ddb9effb73c112932ada7cea3c0620e3e","tarball":"https://registry.npmjs.org/blacksmith/-/blacksmith-0.0.9.tgz","integrity":"sha512-AiZ9D7IB/yMhp4FCgQ4rtzZE6jCqJpfjIJVL3YPeif+yXYj1IJJiiqSZrGItPDczLvbwcE1wPCvmsYxVgtE0qQ==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIF2hJ6CB3PRpdNxZDOBjhHGJaNLV3ubNmev1o/RRpGQkAiEA0HGiNcmNy4uwJaN0iyA3koy/7FzczevpOdJN1jfEHrw="}]},"maintainers":[{"name":"mmalecki","email":"maciej.malecki@notimplemented.org"},{"name":"indexzero","email":"charlie.robbins@gmail.com"},{"name":"jesusabdullah","email":"josh.holbrook@gmail.com"}],"directories":{}},"0.0.10":{"name":"blacksmith","description":"A static site generator built with Node.js, JSDOM, and Weld.","version":"0.0.10","scripts":{"start":"bin/server"},"bin":{"blacksmith":"bin/blacksmith"},"author":{"name":"Nodejitsu","email":"info@nodejitsu.com"},"dependencies":{"blacksmith-sites":"0.0.x","async":"0.1.x","marked":"0.1.x","traverse":"0.4.x","mkdirp":"0.0.x","http-server":"0.2.4","jsdom":"0.2.x","weld":"0.2.1","findit":"0.1.x","flatiron":"0.1.5-1","nconf":"0.4.3","ncp":"0.2.x","colors":"*","optimist":"0.2.x","wordwrap":"0.0.x","rss":"0.0.x","hashish":"0.0.x","prompt":"0.1.x","winston":"0.5.x","cliff":"0.1.x","utile":"0.0.10","alists":"*"},"_npmUser":{"name":"jesusabdullah","email":"josh.holbrook@gmail.com"},"_id":"blacksmith@0.0.10","devDependencies":{},"optionalDependencies":{},"engines":{"node":"*"},"_engineSupported":true,"_npmVersion":"1.1.0-3","_nodeVersion":"v0.6.6","_defaultsLoaded":true,"dist":{"shasum":"2e1c6aa73e9827e793c99a13a3daea6e6ef533be","tarball":"https://registry.npmjs.org/blacksmith/-/blacksmith-0.0.10.tgz","integrity":"sha512-EfdaXRhUINitmS7M2iOBireifLOkMbmN9fJat5B8y4retiK+Kg/eJta16QUFnTbhYjfBYxXVuGTk/mtUTcnG9Q==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQC4sXZ2RRbwieZNWrZn+RQEAASgM3s6c6SMZ+EScz4jLwIgPjYzqZy8O4HKr7RGazDWyp0zV7k9O89KBYhx8EWJF4w="}]},"maintainers":[{"name":"mmalecki","email":"maciej.malecki@notimplemented.org"},{"name":"indexzero","email":"charlie.robbins@gmail.com"},{"name":"jesusabdullah","email":"josh.holbrook@gmail.com"}],"directories":{}},"0.0.11":{"name":"blacksmith","description":"A static site generator built with Node.js, JSDOM, and Weld.","version":"0.0.11","scripts":{"start":"bin/server"},"bin":{"blacksmith":"bin/blacksmith"},"author":{"name":"Nodejitsu","email":"info@nodejitsu.com"},"dependencies":{"blacksmith-sites":"0.0.x","async":"0.1.x","marked":"0.1.x","traverse":"0.4.x","mkdirp":"0.0.x","http-server":"0.2.4","jsdom":"0.2.x","weld":"0.2.1","findit":"0.1.x","flatiron":"0.1.5-1","nconf":"0.4.3","ncp":"0.2.x","colors":"*","optimist":"0.2.x","wordwrap":"0.0.x","rss":"0.0.x","hashish":"0.0.x","prompt":"0.1.x","winston":"0.5.x","cliff":"0.1.x","utile":"0.0.10","alists":"*"},"_npmUser":{"name":"jesusabdullah","email":"josh.holbrook@gmail.com"},"_id":"blacksmith@0.0.11","devDependencies":{},"optionalDependencies":{},"engines":{"node":"*"},"_engineSupported":true,"_npmVersion":"1.1.0-3","_nodeVersion":"v0.6.6","_defaultsLoaded":true,"dist":{"shasum":"b71dbdb238be47dd6d146a2116b568dc137b1841","tarball":"https://registry.npmjs.org/blacksmith/-/blacksmith-0.0.11.tgz","integrity":"sha512-FDgYuY77cRgpihkm3ZsgZTTQx3u6uF+yZ9KV0KiVJY3f7zBZUIcH7CDjSncKPqfGfGPqEgmPSX6yMDGeIQRP0A==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCJyqjRcVCVDwp0TWlcsh52AsgWK2yS+ydfVfA/eC+/1QIhAMa7Q00Vx+pl0GsxI1DU3uxtnFwb6xjMW7OLi/5o+5+7"}]},"maintainers":[{"name":"mmalecki","email":"maciej.malecki@notimplemented.org"},{"name":"indexzero","email":"charlie.robbins@gmail.com"},{"name":"jesusabdullah","email":"josh.holbrook@gmail.com"}],"directories":{}},"0.0.12":{"name":"blacksmith","description":"A static site generator built with Node.js, JSDOM, and Weld.","version":"0.0.12","scripts":{"start":"bin/server"},"bin":{"blacksmith":"bin/blacksmith"},"author":{"name":"Nodejitsu Inc.","email":"info@nodejitsu.com"},"maintainers":[{"name":"mmalecki","email":"maciej.malecki@notimplemented.org"},{"name":"indexzero","email":"charlie.robbins@gmail.com"},{"name":"jesusabdullah","email":"josh.holbrook@gmail.com"},{"name":"marak","email":"marak.squires@gmail.com"}],"dependencies":{"blacksmith-sites":"0.0.x","async":"0.1.x","marked":"0.1.x","traverse":"0.4.x","mkdirp":"0.0.x","http-server":"0.5.x","jsdom":"0.2.x","weld":"0.2.1","findit":"0.1.x","flatiron":"0.1.5-1","nconf":"0.4.3","ncp":"0.2.x","colors":"*","optimist":"0.2.x","wordwrap":"0.0.x","rss":"0.0.x","hashish":"0.0.x","prompt":"0.1.x","winston":"0.5.x","cliff":"0.1.x","utile":"0.0.10","alists":"*"},"_id":"blacksmith@0.0.12","dist":{"shasum":"7bffd4845c53489e52ff3cfc973be8b419c79501","tarball":"https://registry.npmjs.org/blacksmith/-/blacksmith-0.0.12.tgz","integrity":"sha512-P/FrbF55fa9yi3gLzAvx/aBYPE+ruLtL2LL7oHeJk+ipDQMofPFpICAtkaCkBxmswIMpBuN50yNnziDlU9ojnw==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIGAtClgQ/B/PwlmsSp84SoLQestqx7UUcghBh20u1IkgAiBmveF02lObDZOzrnrJv5xcgDZt/+IjEwgycCVX3CSr8A=="}]},"directories":{}},"0.0.13":{"name":"blacksmith","description":"A static site generator built with Node.js, JSDOM, and Weld.","version":"0.0.13","scripts":{"start":"bin/server"},"bin":{"blacksmith":"bin/blacksmith"},"author":{"name":"Nodejitsu Inc.","email":"info@nodejitsu.com"},"maintainers":[{"name":"mmalecki","email":"maciej.malecki@notimplemented.org"},{"name":"indexzero","email":"charlie.robbins@gmail.com"},{"name":"jesusabdullah","email":"josh.holbrook@gmail.com"}],"dependencies":{"blacksmith-sites":"0.0.x","async":"0.1.x","marked":"0.1.x","traverse":"0.4.x","mkdirp":"0.0.x","http-server":"0.5.x","jsdom":"0.2.x","weld":"0.2.1","findit":"0.1.x","flatiron":"0.1.5-1","nconf":"0.4.3","ncp":"0.2.x","colors":"*","optimist":"0.2.x","wordwrap":"0.0.x","rss":"0.0.x","hashish":"0.0.x","prompt":"0.1.x","winston":"0.5.x","cliff":"0.1.x","utile":"0.0.10","alists":"*"},"_id":"blacksmith@0.0.13","dist":{"shasum":"404dd34192645a3137a7e9c9533b22716d3b83eb","tarball":"https://registry.npmjs.org/blacksmith/-/blacksmith-0.0.13.tgz","integrity":"sha512-VTPXHtUR8M+1iR6oyUdHwgPh9EE5C6eakc6ZtdA/9/EN0WIpJP/31f9EsYSb6VfPAF7fzEf1783A4035bGvDgA==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCR+p3H8AvFKoQWkAMOjW5fxHWRLpS04McZiNDOG21IkwIhAIa6pCaE8ykRprKYLAZU3yI+rIGkUKndmnen8BEdk6nl"}]},"_npmVersion":"1.1.66","_npmUser":{"name":"indexzero","email":"charlie.robbins@gmail.com"},"directories":{}},"1.1.2":{"name":"blacksmith","version":"1.1.2","description":"A static site generator built with Node.js, Plates, and Marked.","author":{"name":"Nodejitsu Inc.","email":"info@nodejitsu.com"},"dependencies":{"async":"0.1.x","flatiron":"0.3.0","highlight.js":"7.3.0","marked":"0.2.x","mkdirp":"0.0.x","plates":"0.4.x","timespan":"2.2.x"},"bin":{"blacksmith":"bin/blacksmith"},"devDependencies":{"vows":"0.6.x"},"_id":"blacksmith@1.1.2","dist":{"shasum":"dae2287006bc3f4aa483e6274ea85fd665b02c83","tarball":"https://registry.npmjs.org/blacksmith/-/blacksmith-1.1.2.tgz","integrity":"sha512-raXJfzrso+HAepf0soxYl5S4aRm3XPaf14864xJTpY0ISGn4p5p1hzW2eE/QGuRPVQ1wW7ejkl9yYuqU7I9QRg==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQD3CZINM6v6Fi2Xt4a6R4p1D6swB1LS24EpMUkVXAjXrgIgbXDTZE/gJ8d6brylT4eI+nuP37T7hgtqE4r1gAaC29A="}]},"_npmVersion":"1.1.66","_npmUser":{"name":"indexzero","email":"charlie.robbins@gmail.com"},"maintainers":[{"name":"mmalecki","email":"maciej.malecki@notimplemented.org"},{"name":"indexzero","email":"charlie.robbins@gmail.com"},{"name":"jesusabdullah","email":"josh.holbrook@gmail.com"}]},"1.1.3":{"name":"blacksmith","version":"1.1.3","description":"A static site generator built with Node.js, Plates, and Marked.","author":{"name":"Nodejitsu Inc.","email":"info@nodejitsu.com"},"dependencies":{"async":"0.1.x","flatiron":"0.3.0","highlight.js":"7.3.0","marked":"0.2.x","mkdirp":"0.0.x","plates":"0.4.x","timespan":"2.2.x"},"bin":{"blacksmith":"bin/blacksmith"},"devDependencies":{"vows":"0.6.x"},"_id":"blacksmith@1.1.3","dist":{"shasum":"7c0dfe6b45169ed507e58efa06c4a13d5240a909","tarball":"https://registry.npmjs.org/blacksmith/-/blacksmith-1.1.3.tgz","integrity":"sha512-VqahkcBMD5c1MaXNmj3IP07QsDV5R+9Xx/bB/ljEh8zGWkEObTHtXL8yAd/W04p8c/IxdD/1MgYkJJIn9QKvQw==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIBHGUYe9rYOEAyEwCepvrPDYJfPl5rR7A5C5j/LQqli1AiEA25MFxvJ2CG4h8VdIadv9kizG+6nq6V/AOK/7Ycwe7wg="}]},"_npmVersion":"1.1.66","_npmUser":{"name":"indexzero","email":"charlie.robbins@gmail.com"},"maintainers":[{"name":"mmalecki","email":"maciej.malecki@notimplemented.org"},{"name":"indexzero","email":"charlie.robbins@gmail.com"},{"name":"jesusabdullah","email":"josh.holbrook@gmail.com"}]},"0.0.14":{"name":"blacksmith","description":"A static site generator built with Node.js, JSDOM, and Weld.","version":"0.0.14","scripts":{"start":"bin/server"},"bin":{"blacksmith":"bin/blacksmith"},"author":{"name":"Nodejitsu Inc.","email":"info@nodejitsu.com"},"maintainers":[{"name":"mmalecki","email":"maciej.malecki@notimplemented.org"},{"name":"indexzero","email":"charlie.robbins@gmail.com"}],"dependencies":{"blacksmith-sites":"0.0.x","async":"0.1.x","marked":"0.1.x","traverse":"0.4.x","mkdirp":"0.0.x","http-server":"0.5.x","jsdom":"0.2.x","weld":"0.2.1","findit":"0.1.x","flatiron":"0.1.5-1","nconf":"0.4.3","ncp":"0.2.x","colors":"*","optimist":"0.2.x","wordwrap":"0.0.x","rss":"0.0.x","hashish":"0.0.x","prompt":"0.1.x","winston":"0.5.x","cliff":"0.1.x","utile":"0.0.10","alists":"*"},"_id":"blacksmith@0.0.14","dist":{"shasum":"ba741cf5fc7069ebe6b48cc3a7aeacd5d8985b84","tarball":"https://registry.npmjs.org/blacksmith/-/blacksmith-0.0.14.tgz","integrity":"sha512-V0rtwxWFECTJYtDj9a6Ccw6tF8jEowqJRRm2EomMzIZNc9ActuciDT6mCGRCTyox++Jq5csHRwROBfY90iGokw==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIGLjc7szoJP/xX9no5UHCLtUkUosmRA7L3Yylu4zcga5AiEA3WRWNHlH0gMuAYq9kgsZgqxNIXDvQwk4O0WD45A9ESE="}]},"_from":".","_npmVersion":"1.2.14","_npmUser":{"name":"indexzero","email":"charlie.robbins@gmail.com"}}},"readme":"# blacksmith\n\nA generic static site generator built using `flatiron`, `plates`, and `marked`.\n\n* [Creating a site with Blacksmith](#creating-a-site-with-blacksmith)\n* [Components of a Blacksmith site](#components-of-a-blacksmith-site)\n * [Site Settings](#site-settings)\n * [Layouts](#layouts)\n * [Pages](#pages)\n * [All Page Options](#all-page-options)\n * [Content](#content)\n * [Specifying Metadata](#specifying-metadata)\n * [Content Snippets](#content-snippets)\n * [Code Highlighting](#code-highlighting)\n * [Truncated Content](#truncated-content)\n * [Partials](#partials)\n * [Customizing Partials](#customizing-partials)\n * [Metadata References](#metadata-references)\n * [Conditional Metadata](#conditional-metadata)\n* [How does blacksmith render my Site?](#how-does-blacksmith-render-my-site)\n * [Rendering Procedure](#rendering-procedure)\n * [Rendering Data Structure](#rendering-data-structure)\n* [Tests](#tests)\n\n## Creating a site with `blacksmith` \n\nBlacksmith sites have a specific directory structure for storing the various parts of your site: settings, layout, partials, pages, and content. Content exists in two forms:\n\n* Markdown files that `blacksmith` will render.\n* Supporting content such as css and images.\n\nAll content will be rendered into `/public`. To render a blacksmith site:\n\n**Install Blacksmith**\n\n``` bash\n $ npm install blacksmith -g\n```\n\n**Render a Site**\n\n``` bash\n #\n # Defaults to `cwd`\n #\n $ blacksmith /path/to/your/site\n```\n\nHere's an example of a simple blog that `blacksmith` would render. \n\n``` bash\n/site-name\n #\n # Settings for this blacksmith site.\n #\n .blacksmith\n /content\n #\n # Actual Markdown content to render.\n #\n /posts\n a-post.md\n another-post.md\n /layouts\n #\n # Layouts to use for pages. You can specify \n # multiple layouts, but default.html is ... the default.\n #\n default.html\n /metadata\n #\n # Metadata entities which can be reference in content metdata\n #\n /authors\n author-name.json\n /partials\n #\n # HTML for partials inside of pages\n #\n post.html\n sidebar.html\n /pages\n #\n # Metadata for rendering specific pages\n #\n index.json\n post.json\n /public\n #\n # Any additional files for viewing the site. All\n # rendered HTML will be placed here. e.g.:\n #\n /css\n styles.css\n /img\n favicon.png\n```\n\n## Components of a `blacksmith` site\n\nEach `blacksmith` site defines a hierarchical set of components which can be composed **to create any type of site you want!** A couple of examples:\n\n* A Blog\n* A Documentation Site\n* A Custom Splash Page or Content Site\n\nLets examine each of these components and where they are stored in your filesystem:\n\n### Site Settings\n\nThe settings for a given `blacksmith` site are stored in the `.blacksmith` file located in the root directory of your site. \n\n``` js\n {\n //\n // Default Layout. Specifying a name here will cause Blacksmith to attempt to read\n // /layouts/layout-name.json for rendering info. If no layout-name.json file is found\n // blacksmith will use `/layouts/layout-name.html`\n //\n // Default: default\n //\n \"layout\": \"layout-name\"\n \"pages\": {\n //\n // These settings will be used for all content in\n // /content/posts\n //\n \"post\": {\n \"layout\": \"custom-layout-for-posts\",\n \"partials\": {\n \"html-id\": \"additional-partials\",\n \"another-id\": \"for-this-page-only\"\n }\n }\n }\n }\n```\n\nYou can define settings for all components of your site in the `.blacksmith` file or break them out into individual files within component directories. For example, the above example is equivalent to:\n\n**/.blacksmith**\n\n``` js\n {\n \"layout\": \"layout-name\"\n }\n```\n\n**/pages/post.json**\n\n``` js\n {\n \"layout\": \"custom-layout-for-posts\",\n \"partials\": {\n \"html-id\": \"additional-partials\",\n \"another-id\": \"for-this-page-only\"\n }\n}\n```\n\n### Layouts\n\nLayouts are fully-formed HTML files; **_they are the top of the rendering hierarchy._** All content will be inserted into a layout inside of the HTML element with the `id=\"content\"`. Lets look at the worlds simplest layout:\n\n``` html\n \n \n \tSimple Layout\n \t\n \n \n
\n \n
\n \n \n```\n\nSettings for a layout may specified in your `.blacksmith` file or in `/layouts/layout-name.json`. Lets look at an example:\n\n**/layouts/layout-name.json**\n**NOTE: These properties is not yet supported. See [Roadmap](#roadmap) for more details.**\n\n``` js\n {\n //\n // The \"template\" property specifies which HTML file within the /layouts directory\n // to use when rendering this layout. In this way a single HTML file can be reused with \n // different partials.\n //\n // If no template is specified then blacksmith will look for /layouts/layout-name.html\n // when rendering.\n //\n \"template\": \"shared-layout.html\",\n //\n // The \"partials\" property specifies which HTML partial (or partials) to insert at a given\n // id within the layout. These partials will be rendered with the metadata for a given\n // individual page with content.\n //\n \"partials\": {\n \"sidebar-container\": \"sidebar\",\n //\n // Multiple partials can be concatentated into a single HTML id.\n //\n \"multi-container\": [\"partial1\", \"partial2\"]\n }\n }\n```\n\n### Pages\n\n**Pages** allowed you to specify **what type of content** you wish to render and where to render it within a given layout. As with layouts, pages may specified in your `.blacksmith` file or in `/pages/page-name.json`. Lets look at two examples from our blog:\n\n**/pages/index.json**\n\nThis example of particular interest: **index.json will always be used to render index.html.** In the below example specifies that `blacksmith` should render a list of `post` content, which should be truncated, limited to a maximum of 20 posts. **Note: All lists are sorted descending by the date the content was created.**\n\n``` js\n {\n //\n // The \"content\" property specifies what blacksmith should render\n // inside the HTML element with id=\"content\"\n //\n \"content\": {\n \"list\": \"post\",\n \"truncate\": true,\n \"limit\": 20\n }\n }\n```\n\n**/pages/post.json**\n\nThe rendering information for an individual post is much simpler than our `index.json`. By creating this file, `blacksmith` will:\n\n1. Render all Markdown files in `/content/posts` using the partial found at `/partials/post.html`.\n2. Render the partial found at `/partials/sidebar.html` with the metadata for each Markdown file in `/content/posts` and append it to the HTML element with id=\"content\"\n\n``` js\n {\n \"partials\": {\n \"content\": \"sidebar\"\n }\n }\n```\n\nIt is important to take note of the convention:\n\n``` \n Convention: By default, page content will be rendered in a partial of the same name by default. \n```\n\nAlternatively we could have specified a specific partial to use. If no partial is specified and the default partial is not found then **no metadata would be rendered** (in this case author name, date of post, etc).\n\n#### All Page Options\nA list of all options that can be specified in a `page.json` file are listed below:\n\n``` js\n {\n //\n // Specifies the layout for the page. \n // Default: Layout for the site.\n //\n \"layout\": \"custom-layout-for-page\",\n \n //\n // Specifies a mapping of HTML ids to partial(s). If \"content\" is specified\n // then it is appended after the rendered markdown content.\n //\n \"partials\": {\n \"html-id\": \"partial-name\",\n \"another-id\": [\"multiple-partials\"]\n },\n \n //\n // Case 1: Rendering content with a partial\n //\n \"content\": \"custom-partial\"\n \n //\n // Case 2: Consolidating multiple content sources in a list.\n //\n \"content\": {\n \"list\": \"post\",\n \"truncate\": true,\n \"limit\": 20\n }\n }\n```\n\n### Content\n\nIn `blacksmith`, \"content\" is raw Markdown and supporting files (e.g. images) located within the `/content` directory. Content for individual pages should be placed under `/content/page-name`. \n\nIn our example all content for the `post` page should be placed under `/content/posts`. It is important to take note of the convention:\n\n``` \n Convention: Page names are always singular, but their content folder will always be plural.\n```\n\nThe content for an individual page may also be a directory where supporting files (such as images can be placed). For example if we wanted to create a post with images the directory structure would be:\n\n```\n/site-name\n /content\n /posts\n /post-with-supporting-files\n content.md\n an-image.png\n another-image.png\n some-code.js\n```\n\nThe directory structure will be respected, but the `/content` prefix will be dropped. So the full-url for `an-image.png` would be `http://your-site.com/post-with-supporting-files/an-image.png`.\n\n#### Specifying Metadata\n\n**All metadata associated with content is stored within the individual Markdown files as link definitions prefixed with 'meta:'.** Because of a small limitation in the Markdown format you must use the following syntax to specify metadata:\n\n```\n [meta:author] <> (Author Name)\n [meta:title] <> (A Really Long Title Different from the Filename)\n [meta:nested:values] <> (Are also supported)\n```\n\n#### Content Snippets\n\nIn large content pages it is often useful to have examples or references to other files to be inserted later in rendering. A classic example is **code samples in a blog post.** This is easy in `blacksmith` using **Content Snippets.** Consider the content:\n\n```\n /content\n /dir-post\n index.md\n whatever.js\n```\n\n``` markdown\n This is a piece of markdown content to be rendered later. It has a reference to the file \"whatever.js\"\n \n \n```\n\nIn this example `` in `index.md` would be replaced with the contents of `/content/dir-post/whatever.js`. **Note: Only files with text extensions (.js, .rb, .txt, etc) less than 1MB will be inserted.**\n\n#### Code Highlighting\n\nBecause `blacksmith` uses `marked` we get the benefit of **Github Flavored Markdown** through `highlight.js`. By default code highlighting is enabled. All you need to do is add some CSS for your site. For example:\n\n``` css\n pre {\n border: 1px solid #e0ded3;\n border-radius: 4px;\n margin: 10px 10px 40px 10px;\n padding: 10px;\n background-color: #f0efe8;\n overflow: auto;\n font-size: 14px;\n font-family: Consolas, \"Liberation Mono\", Courier, monospace;\n }\n\n code {\n white-space: pre;\n color: rgba(0,0,0, 1);\n }\n\n code .keyword { font-weight: bold; color: #6089d4; }\n code .string, code .regexp { color: green }\n code .class, code .special { color: #6089d4 }\n code .number { color: red }\n code .comment { color: grey }\n```\n\n#### Truncated Content\n\nIt is necessary to truncate large content pages when rendering them within compilations (i.e. lists). This is supported by `blacksmith` with a special identifier in your Markdown files. For example:\n\n**/content/posts/dir-post/index.markdown**\n\n``` markdown\n A simple post that is truncated with content snippets and metadata that is not used in the post.\n\n ##!!truncate\n\n \n A second file reference with spaces\n < file2.js >\n\n [meta:author]: <> (Charlie index)\n```\n\nWhen rendered in a page like `index.json` with `{ truncate: true }` only the content above `##!!truncate` will be rendered.\n\n### Partials\n\n**Partials** are HTML fragments which are inserted into a layout, a page, or another partial. **All partials are rendered with `plates`**.\n\n#### Default Metadata\n\n``` js\n {\n \"page-details\": {\n \"author\": {\n //\n // Contents of /metdata/authors/author-name.json\n //\n },\n \"href\": \"/full/path/to/page\",\n \"date\": \"Fully qualified date page was published\",\n \"files\": {\n \"js\": [{ \"filename\": \"file1.js\", \"url\": \"/full/path/to/file1.js\" }],\n \"img\": [{ \"filename\": \"img1.png\", \"url\": \"/full/path/to/img1.png\" }]\n }\n }\n }\n```\n\n#### Customizing Partials\n\nAll metadata is placed into partials using a set of simple `plates` conventions. In the future it may be possible to customize these conventions but that is not currently planned.\n\n* _Map URL-like string keys to href=\"keyname\":_ `map.where('href').is(key).use(key).as('href');`\n* _Insert \"content\" into class=\"content\":_ `map.class('content').use('content').as('value');`\n* _Map string keys to class=\"keyname\":_ `map.class(key).use(key)`\n* _Map everything else to class=\"keyname\":_ `map.class(key).use(key);`\n* _Recursively map Array keys:_ `exports.map(metadata[key][0], map);`\n* _Recursively map Object keys:_ `exports.map(metadata[key], map);`\n\n#### Conditional Metadata\n\nSome content should only exist in partials when a given key is present in the metadata. This is supported by `blacksmith` in the following way: _The keys in `remove` must be specified at the fully qualified path into an Object._\n\n**/partials/partial-name.json**\n\n``` js\n {\n \"remove\": {\n \"page-details\": {\n \"author\": [\"github\", \"twitter\"]\n }\n }\n }\n```\n\nIn the corresponding HTML file for the partial any elements with \"class=if-[keyname]\" will be removed if the is no value for `keyname`. In the above example using the following template:\n\n**/partials/partial-name.html**\n\n``` html\n
\n```\n\nand this set of metadata:\n\n``` js\n {\n \"page-details\": {\n \"author\": {\n \"name\": \"Charlie Robbins\",\n \"github\": \"indexzero\",\n \"github-url\": \"https://github.com/indexzero\"\n }\n }\n }\n```\n\nThe output would be the following. **Notice how everything inside `if-twitter` has been removed.**\n\n``` html\n
\n```\n\n#### Metadata References\n\nIt is useful when writing a content page to use a key to reference a larger section of metadata stored elsewhere. These other sections of metadata are called **metadata references** and are loaded by `blacksmith` from `/metadata`. For example:\n\n**/metdata/dogs/sparky-mcpherson.json**\n```\n {\n \"name\": \"sparky-mcpherson\",\n \"breed\": \"labridoodle\",\n \"color\": \"brown\",\n \"age\": \"3\",\n \"temperment\": \"friendly\"\n }\n```\n\n**/content/posts/a-post.md**\n\n``` markdown\n (... Rest of Content ...) \n [meta:dog] <> (Sparky McPherson)\n```\n\nWhen the content for this page finally gets rendered to a partial the metadata will not be `{ 'dog': 'sparky' }`, it will be the entire object stored in `/metadata/dogs/sparky.json`. By convention:\n\n```\n Convention: For a given `key:value` blacksmith will lookup metadata references for the `value`\n in the directory named with the plural of that `key`. \n```\n\nIn the above example the `key:value` pair is `dog:Sparky Mcpherson` so we attempt to lookup `sparky-mcpherson` within `/metadata/dogs/sparky-mcpherson.json`.\n\n**Note:** \"Authors\" is a special metadata reference which will always be within the `metadata.page-details`.\n\n## How does `blacksmith` render my Site?\n\n**It's safe to skip this if you're not tinkering with `blacksmith` internals.** \n\n### Rendering Process\n\nIn order to render list pages with all options supported by `blacksmith` it is necessary to perform multiple rendering passes on a given site to fully render it. Lets examine that process start to finish:\n\n* **1. Rendering starts**\n\nRendering starts when `blacksmith('/full/path/to/your/site', function () { ... })` is invoked. This tells `blacksmith` where the root directory for a given site is.\n\n* **2. Load all HTML and rendering settings**\n\nInside `Site.prototype.load` will load all HTML and rendering settings stored in:\n\n * .blacksmith\n * /layouts/*.json || *.html\n * /pages/*.json\n * /partials/*.html\n\nWe need to load all of these files before any rendering can begin because they store the necessary settings for rendering.\n\n* **3. Read everything under `/content`**\n\nBefore layout, page, and partial rendering can take place all content (i.e. Markdown and supporting files) must be known to `blacksmith`. In our example how can we render the page represented by `/pages/index.json` without all rendered content? `Site.prototype.readContent` recursively reads `/content` building this data structure:\n\n```\n/content\n /posts\n a-post.md\n another-post.md\n /dir-post\n file1.js\n file2.js\n index.markdown\n```\n\n``` js\n{\n posts: {\n \"a-post\": { _content: { html: \"..\", markdown: \"..\", metadata: { ... } } },\n \"another-post\": { _content: { html: \"..\", markdown: \"..\", metadata: { ... } } }\n \"dir-post\": {\n _content: {\n html: \"HTML rendered from Markdown\", \n markdown: \"Markdown in index.markdown\",\n metadata: {\n \"page-details\": {\n source: \"/dir-post/index.markdown\",\n title: \"Title of page in metadata\" || \"href of page\",\n date: \"Saturday, November 10, 2012\",\n href: \"/dir-post\",\n \"files\": {\n \"js\": [{ \"filename\": \"file1.js\", \"url\": \"/full/path/to/file1.js\" }],\n \"img\": [{ \"filename\": \"img1.png\", \"url\": \"/full/path/to/img1.png\" }]\n }\n }\n }\n },\n _files: ['file1.js', 'file2.js']\n }\n }\n}\n```\n\n* 4. **Render all pages**\n\n### Rendering Data Structure\nAs we discussed `blacksmith` uses hierarchical rendering components. Each component inherits the relevant properties from its parent entity. The full hierarchy is:\n\n* Site\n * Layout\n * Partial\n * Page\n * Content\n * Partial\n\nNotice that partials can _be specified by both layouts and pages._ In the event of a conflict the partials specified by the page will always be preferred.\n\nLets examine a fully-formed data structure for rendering each of our rendering data structures:\n\n**Page**\n\n``` js\n {\n //\n // There are all inherited from Site and Layout that this \n // page is associated with\n //\n \"layout\": \"layout-name\"\n \"html\": {\n \"layouts\": { ... },\n \"partials\": { ... }\n },\n \"partials\": {\n \"html-id\": \"sidebar\",\n \"another-id\": \"breadcrumbs\",\n \"multiple-partials\": [\"that-can\", \"be-overridden\"]\n },\n //\n // Metadata is extracted from link definitions on the page prefixed,\n // with \"meta:{key}\". The {key} is what is stored in the metadata property.\n //\n // e.g. [meta:author] <> (indexzero) \n //\n \"metadata\": {\n \"author\": \"indexzero\"\n }\n }\n```\n\n## Tests\nAll tests are written with [vows][0] and can be run with [npm][1]:\n\n``` bash\n $ npm test\n```\n\n## Roadmap\n\n1. RSS Feed\n2. Only render \"dirty\" files (i.e. those not modified since last render).\n3. Customize list sorting by key and direction.\n4. Support nested partials.\n5. Support rendering page depths greater than 1.\n6. Support \"template\" and \"partials\" in layouts.\n7. Investigate this bug: https://github.com/flatiron/plates/issues/93\n\n#### License: MIT\n#### Author: [Charlie Robbins](http://github.com/indexzero)\n\n[0]: http://vowsjs.org\n[1]: http://npmjs.org","maintainers":[{"name":"indexzero","email":"charlie.robbins@gmail.com"}],"time":{"modified":"2022-06-13T04:45:25.336Z","created":"2012-01-14T13:48:53.559Z","0.0.7":"2012-01-14T13:48:55.616Z","0.0.8":"2012-01-14T13:58:47.770Z","0.0.9":"2012-01-31T20:42:17.288Z","0.0.10":"2012-02-02T20:44:53.354Z","0.0.11":"2012-02-08T21:23:15.723Z","0.0.12":"2012-08-13T13:37:05.702Z","1.0.1":"2012-11-14T07:56:20.601Z","1.1.0":"2012-11-17T03:58:34.083Z","1.1.1":"2012-11-26T23:16:23.495Z","1.1.2":"2012-12-11T18:24:33.180Z","0.0.13":"2012-11-27T11:48:55.055Z","1.1.3":"2012-12-12T04:00:53.621Z","0.0.14":"2013-08-02T22:37:27.414Z"},"author":{"name":"Nodejitsu Inc.","email":"info@nodejitsu.com"},"users":{"blakmatrix":true,"tigefa":true,"jlsjonas":true},"readmeFilename":"README.md"}