This is a simple Gulp pipeline to convert particularly organized Markdown content to static html. This is a quick personal project which I just put up here so others might benefit. It is not supported.
You can find my website at pnksmr.fr.
- Install Gulp if you haven't already done so
- Run
npm update && npm install - Add a
/srcfolder withtemplateandcontentfolders
For an example see my website's content repo- The
/src/templateshould contain:index.html, your default templateimages/for any imagesscss/styles.scssfor your styles
- Put you site content in
/src/content/src/contentwill be the root of your site in/pages- All files starting with
%are ignored, so you can use that for files which you want to include without generating a separate html file for them - Any
.mdor.markdownfiles will be converted tohtmland wrapped insrc/layout.html - Any other files will be copied as is
- The
- Run
gulp buildand watch/pagesappear with your new website
I advice you to fork this project if you really want to use it, because changes might break your site at any time.
I opted for a default template name of layout.html and the Handlebars template engine. The contents of the page will be present in the contents variable.
I also use FrontMatter to be able to add or modify template variables. This means you can make exceptions for the used template or engine by providing the layout (relative to the template directory) and engine variables. I also use the title variable to set the page title, and print a warning if it has not been set.
A very basic layout.html to use (using Handlebars):
<html>
<head>
<title>{{title}}</title>
</head>
<body>
{{{contents}}}
</body>
</html>Using that with the following Markdown file:
---
layout: layout.html
engine: handlebars
title: Hello world
---
# HelloWould deliver the following html:
<html>
<head>
<title>Hello world</title>
</head>
<body>
<h1>Hello</h1>
</body>
</html>You can of course use more variables besides title to further modify your template.
Thanks to gulp-file-include you can include files using @@include("./%include.md") anywhere in the file. Files prefixed with % are not processed on their own and do not show up in ./pages by themselves.
- For my use, I wrap the content in an
<article>tag. Any<p>in there with only images in it will get animagesclass which is useful for the style I am using. If you do not want this remove the appropriate from thecontent_markdowntask. - A (rudimentary and inelegantly implemented) way to add footnotes is available. The idea is borrowed from MultiMarkDown. You can add a footnote as follows:
Here is some text containing a footnote.[^samplefootnote]
[^samplefootnote]: Here is the text of the footnote itself.The reference will link to the footnote and the footnote will link back to the reference.
- Gulp
- Del
- Handlebars
- gulp-sass
- gulp-front-matter
- gulp-markdown
- gulp-layout
- gulp-file-include
- gulp-dom
- gulp-replace
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
