Future publication
- - -Published 1 March 2016, 16 words, 1-minute read
- - -This article will only appear if the site is built is run after 1 March, 2016.
- - - - - - -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Build
- - -Published 3 March 2020, 55 words, 1-minute read
- - -To build and launch the site in a test server using Browsersync:
-npm start(Stop the server with Ctrl+C.)
To build the site for production and compress HTML files:
-npm run productionThe site is built in the /build folder.
Note you may want to change the siteMeta.domain and siteMeta.rootpath on lines 52 and 53 of ./build.js.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- docs
- - -This section provides an overview of core code and concepts.
- - - --
-
-
-
-
-
-
Installation
-2 March 2020
- -How to install this demonstration code.
- -
- -
-
-
-
Build
-3 March 2020
- -How to build the static site using Metalsmith.
- -
- -
-
-
-
Site files
-26 February 2020
- -A description of the source files used to build a website
- -
- -
-
-
-
Page definitions
-3 March 2020
- -How pages are defined in the source folder.
- -
- -
-
-
-
Custom plugins
-2 March 2020
- -The custom plugins used to create this website.
- -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Installation
- - -Published 2 March 2020, 27 words, 1-minute read
- - -Please ensure Node.js and Git are installed on your system.
-Download the demonstration code and switch to directory:
-git clone git@github.com:dashdev-suite/dashdev-website.git - cd metalsmith-demo
-Install dependencies:
-npm install
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Page definitions
- - -Published 3 March 2020, 194 words, 1-minute read
- - -Each sub-folder in src/html is a website section. Pages named index.md are the default page in section. File paths are translated to permalinks, e.g.
src/html/article/mypage.mdis rendered to:
-build/article/mypage/index.htmlPages use YAML front-matter defined at the top. This can be referenced in templates or during the build process, e.g.
----
-title: My page title
-description: A description of this page for meta tags and page lists.
-layout: page.html
-priority: 0.9
-publish: 2016-06-01
-date: 2016-06-01
----All items are optional. Note:
--
-
layoutdefaults topage.htmlunlessmetadata.layoutis defined for the page collection (see theuse(collections({ ... })code inbuild.js).
-priorityis a number between 0 (low) and 1 (high) which is used to order menus and define XML sitemaps.
-publishcan be setdraft,privateor a future date to ensure it is not published until required.
-dateis the date of the article. If not set, a futurepublishdate or the file creation date is used.
-
The page content is defined in markdown, HTML syntax or both below the front-matter section. The content can include Handlebars partials from the src/partials folder, e.g.
{{> partialname }}where partialname is the partial filename without its .html extension.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Custom plugins
- - -Published 2 March 2020, 77 words, 1-minute read
- - -The build.js file defines how the site is built using Metalsmith and various plugins.
Several custom plugins have been created specifically for this site:
--
-
lib/metalsmith-debug.js: output debugging information to the console.
-lib/metalsmith-setdate.js: ensure each page has a date. If adateis not defined in the page's front-matter, it is presumed to be the publish or file creation date.
-lib/metalsmith-moremeta.js: applies further metadata to each page including the root folder, a default layout, primary and secondary navigation.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Site files
- - -Published 26 February 2020, 57 words, 1-minute read
- - -All files in the src folder can be edited:
-
-
- pages are created as markdown files in the
src/htmlfolder and sub-folders.
- - static assets such as CSS, JavaScript and image files are created in
src/assets. These are copied without modification tobuild/.
- - page templates are defined in
src/template.
- - reusable partials (chunks of HTML code) are declared in
src/partials.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- 
This is a static website generated using the Node.js-powered Metalsmith and various published and custom plugins.
-This is a demonstration rather than a recommended way to build a static site. Your requirements will be different. Please use any part of the code as you wish.
-Where could you use Metalsmith?
-Metalsmith could be used to create:
--
-
- a fast static website with minimal server-side requirements -
- technical documentation -
- an eBook -
- application prototypes -
- build tools or project scaffolding -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Articles
- - -A selection of articles is available in this section.
- - - --
-
-
-
-
-
-
Usage options
-14 March 2016
- -What type of project could benefit from Metalsmith?
- -
- -
-
-
-
Gotchas
-10 March 2016
- -Issues and workarounds when using Metalsmith.
- -
- -
-
-
-
Gulp
-2 March 2016
- -Do you need Gulp? Can it be integrated with Metalsmith?
- -
- -
-
-
-
Future publication
-1 March 2016
- -This article will be published after 1 March, 2016.
- -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Usage options
- - -Published 14 March 2016, 47 words, 1-minute read
- - -Metalsmith could be used to create any number of resources, including:
--
-
- a fast static website with minimal server-side requirements -
- technical documentation -
- an eBook -
- application prototypes -
- build tools or project scaffolding -
The markdown files can be converted to other files types using plugins such as metalsmith-pandoc or metalsmith-pdf.
- - - - - - -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Gotchas
- - -Published 10 March 2016, 127 words, 1-minute read
- - -Not everything is necessarily straight-forward in the Metalsmith world…
-Incompatible plugins
-Some plugins clash with another. For example, metalsmith-rootpath which calculates relative roots does not play nicely with metalsmith-permalinks which creates custom folder structures.
-Note: lib/metalsmith-moremeta in this project sets a correct root variable whether permalinks are used or not.
Plugin order can be critical
-One plugins may depend on another or conflict if placed the wrong way around. For example, the RSS-generating metalsmith-feed plugin must be called after metalsmith-layouts to ensure rss.xml is not generated within a page template.
Browsersync build issues
-When Browsersync is running and files are edited, collections are re-parsed but the old data remains. This can cause menus and next/back links to be incorrect. To fix this, stop and restart the build.
- - - - - - -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Gulp
- - -Published 2 March 2016, 141 words, 1-minute read
- - -Metalsmith has plugins for CSS pre-processing with Sass, image minification, file concatenation, uglification and more. The build code will be familiar to anyone with Gulp experience.
-Do you still need Gulp?
-Metalsmith is often enough for simpler workflows. However, Gulp has a more extensive range of plugins and permits complex build activities such as linting and PostCSS processing with auto-prefixer.
-Metalsmith can be used within any Gulp task, e.g.
-var
- gulp = require('gulp'),
- metalsmith = require('metalsmith'),
- publish = require('metalsmith-publish'),
- markdown = require('metalsmith-markdown');
-
-// build HTML files using Metalsmith
-gulp.task('html', function() {
-
- var ms = metalsmith(dir.base)
- .clean(false)
- .source('src/html/')
- .destination('build')
- .use(publish())
- .use(markdown())
- .build(function(err) {
- if (err) throw err;
- });
-
-});Further Gulp tasks can then be added. Note .clean(false) ensures Metalsmith never wipes the build folder when other tasks are active.
There are a number of Gulp/Metalsmith integration plugins although they are rarely necessary.
- - - - - - -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Future publication
- - -Published 1 March 2016, 16 words, 1-minute read
- - -This article will only appear if the site is built is run after 1 March, 2016.
- - - - - - -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- tutorials
- -This section provides an overview of core code and concepts.
- - -