Yet another opinionated static site generator based on markdown files.
Here's a live example of a site made using Sparkdown.
What do you mean?
Takes a source directory of markdown files and spits out a website.
What's it good for?
Sparkdown will work for sites that are content-heavy. For example, portfolio websites, blogs and documentation websites. It's fairly easy to get a continuous-delivery pipeline set up using git-hooks or otherwise, making it a good solution for open-source project documentation.
Sparkdown is opinionated, and you don't get much control over how the generated site looks. If you want more control, use something like Jekyll or Hugo.
mkdir website; cd websiteyarn inityarn global add sparkdown
mkdir website; cd websitenpm initnpm install -g sparkdown
Make a configuration file:
Write to your
sparkdown.json file. Sparkdown comes with some sensible defaults, but here's an example:
source: Source directory of markdown files
output: Directory where sparkdown will generate HTML files
bodyFont: Any valid google webfont
monospaceFont: Any valid google webfont (used when rendering
author: Populates the author meta tag
description: Populates the description meta tag
title- The base title for the site. Note this gets updated per-page automatically
Alternatively, you can add a
sparkdown key to your
package.json file and sparkdown will read from it instead of the config file:
Create markdown files in the directory you specified in the
source key in your config. The following examples use
Sparkdown will automatically pretty-print the name of the file to the end of the title for you. Using the configuration shown above, a file with the path:
Will generate a HTML file with the title:
Sparkdown - My First Post
Directories & Menu
Sparkdown will create a menu for you. It's always visible on desktop screens, and tucks away behind a button on mobile.
Directories can be used as a makeshift category system to nest pages. Markdown files that are placed inside a directory will be placed inside a menu item who's title is the name of the directory. For example, consider the following directory structure:
This directory structure will result in the following menu:
Home Contact Blog My First Post My Second Post Projects First Project Second Project
A subtlety thats worth noting is that directories that contain an
index.md file will have the directory title in the menu link to the
index. If there is no
index in the directory, sparkdown will link the directory to the first file it can find inside the directory. You can see the difference displayed above between the
There isn't a limit to the level of directory nesting sparkdown can handle, though it starts looking a bit silly if you use more than 2 levels.
Sparkdown pretty-prints directory and file names inside the menu. There isn't really any way to order the files other than alphabetically as per the file-system.
Sparkdown assumes that you have a
index.md file at the root of your
src directory. Sparkdown places a special
Home link at the top of the menu that links back to the
You can link to pages from within your site using relative paths. For example, if I'm writing the
My Second Post page from the example above, and I want to link back to
My First Post, I'll write the markdown as follows:
# My Second PostIf you haven't done so already, check out the
Note that I've left out the extension.
You can traverse directories too, for example, if I want to link to the contact page from the example above, I'll write the markdown as follows:
# My Second PostFeel free to
You'll need to link explicitly to index pages:
# My Second PostFeel free to or head back
Linking to external sites is pretty standard:
# My Second PostProudly powered by
Sparkdown comes with
turbolinks preconfigured for 💯 perf.
Run the following from the root directory of your project (where your
Sparkdown will recursively read all
.md files from your
src directory including any subdirectories and convert them into
.html files in your output directory.
Take a look at the example project for an details on how to use markdown (particular attention goes to how you can do relative links between pages).