metalpress

<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"> <channel> <title><![CDATA[New Site]]></title> <description><![CDATA[New Site]]></description> <link>http://testsite.com</link> <generator>RSS for Node</generator> <lastBuildDate>Tue, 03 May 2016 20:10:03 GMT</lastBuildDate> <atom:link href="http://testsite.com/rss.xml" rel="self" type="application/rss+xml"/> <item> <title><![CDATA[Dreaming]]></title> <description><![CDATA[<!DOCTYPE html> <html lang="en"> <head></head> <body> There's a total of 395 static site generators <a href="https://staticsitegenerators.net/">out there</a> on the web, and probably even more found on Github. It's pretty clear to see that developers want good tooling to rapidly build static sites. Github advocates for <a href="https://jekyllrb.com/">Jekyll</a> and allows you to freely <a href="https://pages.github.com/">host</a> a Jekyll site as a Organization or Project. A lot of people might be okay with this solution for a simple blog or open source project, however if you want a faster development environment and more flexibility to customize the functionality of your site, you might find this solution limiting. As I was rebuilding my site, I definitely wanted to shift off of Jekyll and go with something that allowed for extending functionality with Javasrcipt in ES6. <h2 id="metalsmith">Metalsmith</h2> <a href="https://github.com/segmentio/metalsmith">Metalsmith</a> is an extremely pluggable static site generator built with Javascript and Node.js by the team over at <a href="https://segment.com/home">Segment</a>. It has a simple design in and of itself, however the power comes in from the number of <a href="https://github.com/lambtron/awesome-metalsmith/blob/master/PLUGINS.md">plugins</a> available in the Metalsmith ecosystem. In this post we'll take a look at some of these plugins and how they might fit into a simple workflow of building a static blog. To get started let's create a new directory: <code>mkdir metalsmith-blog</code> and initialize it with <code>npm init</code>. You can build your site with either the Metalsmith CLI or the Javascript API. Let's take a look at both and you'll get to see which one might work better for your particular use case. <h2 id="cli">CLI</h2> To use the Metalsmith CLI, let's install it globally with <code>npm i -g metalsmith</code>. In order for metalsmith to do it's work, we'll need to create a <code>metalsmith.json</code> file with a configuration for our site: <pre><code class="hljs json">{ "source": "src", "destination": "build", "plugins": {} }</code></pre> With this configuration, Metalsmith will read all the files in the source directory (<code>src</code>) and copy them into the destination (<code>build</code>) directory. As you can see we'll also have the opportunity to include plugins that will process our files along the way. Let's add a few plugins that we can use to build a basic blog page with posts. We'll need a way to render markdown files to html, so let's install <code>metalsmith-markdown</code>. <pre><code class="hljs sh">$ npm i metalsmith-markdown --save</code></pre> Great, we'll also need a way to render our markdown in some sort of template. Metalsmith used to have a <code>metalsmith-templates</code> plugin, however this has been divided into two smaller plugins named <code>metalsmith-layouts</code> and <code>metalsmith-in-place</code>. At first, I wasn't sure the difference here, but there's a difference between the two. <code>metalsmith-in-place</code> renders files within your <code>src</code> directory, whereas <code>metalsmith-layouts</code> renders files from a root <code>layouts</code> directory. This allows you to separate layout specific code from source-specific template logic that may exist in a source file. One of the benefits of Metalsmith is how flexible it is in regards to templating. With consolidate.js behind the scenes, you can use any <a href="">templating engine</a> of your choice. In this case, we'll use liquid because of it's familiar for people migrating from Jekyll. Let's install them both: <pre><code class="hljs sh">$ npm i metalsmith-layouts metalsmith-in-place --save</code></pre> Let's also install tinyliquid for our template engine. <pre><code class="hljs sh">$ npm i tinyliquid --save</code></pre> Great, lastly we'll need a way to output a collection of posts and create pretty permalinks such as <code>/blog/metalsmith-post/</code> versus <code>/blog/metalsmith-post/index.html</code>. Let's do that by installing <code>metalsmith-collections</code> and <code>metalsmith-permalinks</code>. <pre><code class="hljs sh">$ npm i metalsmith-permalinks metalsmith-collections --save</code></pre> Cool! Now let's set up our plugins in our <code>metalsmith.json</code>: <pre><code class="hljs json">"plugins": { "metalsmith-collections": { "posts": { "pattern": "blog/!(index).md" } }, "metalsmith-markdown": { "gfm": true }, "metalsmith-layouts": { "engine": "liquid", "directory": "layouts", "includeDir": "layouts/includes" }, "metalsmith-in-place": { "engine": "liquid", "pattern": "**/*.html", "includeDir": "layouts/includes" }, "metalsmith-permalinks": { "pattern": "blog/:title" } }</code></pre> You'll notice we're configuring each plugin with it's respective options. You can learn more about the options at each plugin's Github repo. Here we're collecting posts from our blog directory, rending layouts and source files while allowing us to utilize liquid's includes <code>{% include partial-name %}</code>, and creating permalinks for our posts with the <code>title</code> from our post front-matter. Now let's set up some layouts we can use for our landing page, post, and blog page: <pre><code class="hljs sh">$ mkdir -p layouts/includes && touch layouts/base.liquid && touch layouts/includes/blog.liquid && touch layouts/post.liquid</code></pre> <h4 id="layouts-base-liquid">layouts/base.liquid</h4> <pre><code class="hljs html"><!DOCTYPE html> <html> <head> <title>World Traveler</title> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css"> <link rel="stylesheet" href="/css/style.css"> </head> <body> <header class="header"> <div class="navbar"> <a class="navbar-brand" href="/">World Traveler</a> <ul class="nav navbar-nav"> <li> <a href="/">Home</a> </li> <li> <a href="/blog">Blog</a> </li> </ul> </div> </header> <div class="container"> <div class="row"> <div class="col-md-12"> <div class="content"> {{ contents }} </div> </div> </div> </div> </body> </html></code></pre> <h4 id="layouts-includes-blog-liquid">layouts/includes/blog.liquid</h4> <pre><code class="hljs html"><div class="posts"> <ul class="posts__list"> {% for post in collections.posts %} <li class="post"> <a href="/blog/{{ post.title | downcase | split: ' ' | join: '-'}}">{{ post.title }}</a> </li> {% endfor %} </ul> </div></code></pre> Here we're looping over our post collection with <code>collections.posts</code> and including our post partial passing in the post data. <h4 id="layouts-post-liquid">layouts/post.liquid</h4> <pre><code class="hljs html"><!DOCTYPE html> <html> <head> <title>World Traveler</title> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css"> </head> <body> <header class="header"> <div class="navbar"> <a class="navbar-brand" href="/">World Traveler</a> <ul class="nav navbar-nav"> <li> <a href="/">Home</a> </li> <li> <a href="/blog">Blog</a> </li> </ul> </div> </header> <div class="container"> <div class="row"> <div class="col-md-12"> <div class="post"> <h3 class="post-title">{{ title }}</h3> <p class="post-date">{{ date | date: "%b %d, %Y" }}</p> <div class="post-content"> {{ contents }} </div> </div> </div> </div> </div> </body> </html></code></pre> Finally, let's create a <code>src</code> directory and add in a markdown for a landing, blog page, and new blog post: <pre><code class="hljs">$ mkdir -p src/blog && touch src/index.md && touch src/blog/index.md && touch src/blog/2015-11-05-new-york-visit.md</code></pre> <h4 id="src-index-md">src/index.md</h4> <pre><code class="hljs md">--- layout: base.liquid title: World Traveler permalink: false --- A site about my travels...</code></pre> You'll notice here we're setting <code>permalink</code> to false. This tells our permalink plugin not to render this page under <code>blog</code> which we have set up as our permalink path. <h4 id="src-blog-index-md">src/blog/index.md</h4> <pre><code class="hljs md">--- layout: base.liquid title: Blog permalink: false --- {% include blog %}</code></pre> <h4 id="src-posts-2015-11-05-new-york-visit-md">src/posts/2015-11-05-new-york-visit.md</h4> <pre><code class="hljs">--- layout: post.liquid title: Traveling to New York date: 2015-11-06 --- This month we'll learn about the delights of New York City...</code></pre> Now let's add a npm script to run the CLI with <code>npm run build</code>: <pre><code class="hljs json">{ "scripts": { "build": "metalsmith" } }</code></pre> Finally we can run: <pre><code class="hljs sh">$ npm run build</code></pre> Here we have a simple landing page and blog page with a blog post. Let's add some styling with sass. <pre><code class="hljs sh">$ npm i metalsmith-sass --save</code></pre> <pre><code class="hljs json">"metalsmith-sass": { "outputDir": "css" }</code></pre> <pre><code class="hljs sh">$ mkdir src/sass && touch src/sass/style.scss</code></pre> <h4 id="src-styles-style-scss">src/styles/style.scss</h4> <pre><code>body { margin: 0; font-family: 'Helvetica'; font-weight: 100; font-size: 18px; line-height: 1.5; } a { color: #053580; font-weight: 400; text-shadow: 0px 0px 0px #fff; } .content { padding: 20px; } .navbar { padding: 20px; }</code></pre> And we'll add our link tag: <code><link rel="stylesheet" href="/css/style.css"></code> Let's also add a nice header image courtesy of <a href="https://unsplash.com/photos/SR68yPh06As">Unsplash</a> Add the jpeg in <code>src/assets</code>. <pre><code>.header { background-image: url("/assets/header.jpeg"); background-size: cover; min-height: 300px; background-position: center -95%; }</code></pre> Let's run the build again and start a local server. <pre><code class="hljs sh">$ npm run build && serve build</code></pre> So now that we have a pretty good sense of what Metalsmith can do, let's take a look at how you might run the same build using the API with Babel and finish off our blog by minifying our html. This will make our site nice and fast! If you aren't already up to speed with Babel 6, go ahead and install the CLI with: <code>npm i -g babel-cli</code>. Then we can set up our <code>.babelrc</code>. <pre><code class="hljs sh">$ touch .babelrc && npm install babel-preset-es2015 --save-dev</code></pre> <h4 id="-babelrc">.babelrc</h4> <pre><code class="hljs json">{ "presets": ["es2015"] }</code></pre> <h2 id="metalsmith-s-api">Metalsmith's API</h2> Let's firstly install <code>metalsmith</code>. <pre><code class="hljs sh">$ npm i metalsmith --save</code></pre> Next, let's create a <code>build.js</code> and write our build script. <pre><code class="hljs sh">$ touch build.js</code></pre> <pre><code class="hljs js">import Metalsmith from 'metalsmith'; import collections from 'metalsmith-collections'; import layouts from 'metalsmith-layouts'; import inPlace from 'metalsmith-in-place'; import markdown from 'metalsmith-markdown'; import permalinks from 'metalsmith-permalinks'; import sass from 'metalsmith-sass'; Metalsmith(__dirname) .use(collections({ posts: { pattern: 'blog/!(index).md', sortBy: 'date', reverse: true } })) .use(sass({ outputDir: 'css' })) .use(markdown({ gfm: true })) .use(permalinks({ pattern: 'blog/:title' })) .use(layouts({ engine: 'liquid', directory: 'layouts', includeDir: 'layouts/includes' })) .use(inPlace({ engine: 'liquid', pattern: '**/*.html', includeDir: 'layouts/includes' })) .build(function () { console.log('Cheers!'); });</code></pre> Great, here we can see Metalsmith uses <code>.use</code> to invoke the plugins in order from top to bottom similar to express middleware, each function gets invoked with all the files from the previous function, processed and passed along. Let's run our build with <code>babel-node</code>: <pre><code class="hljs sh">$ babel-node build.js</code></pre> Lastly, let's add html minification. <pre><code class="hljs sh">$ npm i metalsmith-html-minifier --save</code></pre> <pre><code class="hljs js">... import htmlMinifier from 'metalsmith-html-minifier'; ... .use(htmlMinifier()) .build(function () { console.log('Cheers!'); })</code></pre> And now we can adjust our build script. <pre><code class="hljs sh">{ "scripts": { "build": "babel-node build.js" } }</code></pre> Again, let's run our build. <pre><code class="hljs sh">$ npm run build</code></pre> <h2 id="conclusion">Conclusion</h2> As you can see Metalsmith is extremely flexible and has a number of <a href="http://www.metalsmith.io/#the-plugins">plugins</a> you can choose from to extend your site to fit your needs. There are plugins ranging from tag generators, to s3 upload, to browserify and webpack bundling. You'll definitely have the flexibility and you can also run your builds nicely with ES6 using Babel 6. From here, you may want to expand the structure of your layouts and src directories to better suite your project. Also, if you're looking for a way to build multiple permalinks, you can use something like <a href="https://github.com/ericgj/metalsmith-branch">metalsmith-branch</a> to break out the permalinks for different paths. I hope you were able to learn more about Metalsmith and you'll consider using it on your next project! Check out the <a href="http://cameronjroe.com/metalsmith-blog/">Demo</a> and <a href="https://github.com/cameronjroe/metalsmith-blog">Code</a>. </body> </html> ]]></description> <guid isPermaLink="false">Dreaming</guid> <pubDate>Tue, 15 Mar 2016 16:00:00 GMT</pubDate> </item> </channel> </rss>