Gumdrop
Zero-configuration script to display Markdown documents as static HTML pages
Gumdrop is designed to be an easy to use, standalone script that can generate websites and documentations written in Markdown. It dinamically loads all its dependencies from a CDN (including the Markdown parser) and does not require any configuration or initialization.
Installation
Gumdrop does not require installation you just have to load it into an HTML document with a script
tag.
Usage
To create a static website with Markdown all you need to to is to create a HTML template (index.html
) on your file server and add Gumdrop as an external script file.
Be aware, that you have to serve your files via
http
/https
protocol, as thefile
protocol does not support fetch requests.
Markdown files in the pages
folder can be loaded. Gumdrop watches the hash fragment of the URL and loads the corresponding Markdown file from the pages
folder. The parsed Markdown files get rendered in the <main>
HTML node if present, in body
otherwise. The default file that gets loaded if no file is specified is pages/index.md
. To create a link to another file in the pages
folder simply create a link with its name prefixed by #!/
.
[Link to about.md](#!/about)
Static resources (e.g. images) can be loaded from any folder that is served by your file server, paths are relative to index.html
. Error pages for various HTTP errors can be placed in the errors
folder. Each file should be named according to the HTTP error code it represents (e.g. errors/404.md
).
Additional data can be specified for your documents in a YAML Front Matter. You can access this data in any of your Markdown documents with mustache templates.
You can also use separate files to store data and link these resource files to a document in the front matter. Resource files can use YAML (default), JSON or Markdown type. Any value in a document's front matter that is annotated with the !file
type is considered a file resource. File paths starting with a leading /
are relative to index.html
, if the leading /
is missing then the data
folder is assumed as the resource location. If no file type (extension) is given then the .yaml
extension is assumed. For .md
resource files the returned value will be the rendered Markdown document.
# data/todo.yaml todos: - title: First todo text: Complete your first assignment completed: true - title: YAML text: Learn more about YAML Front Matters completed: false
---
todos: !file todo.yaml
---
{{#todos}}
- **{{title}}**: {{text}} {{#completed}}(✔){{/completed}}
{{/todos}}
Features
- Zero configuration, no initialization needed
- No server side code, only needs a static file server
- No build/generation step, it's just files you serve
- Extra Markdown features via ExtraMark
- Navigation by fetch requests
- Local caching of files for faster load times
- Additional data in front matter and data files handled by mustache templates
- Error pages for various HTTP error codes (404, 500, 300)
Syntax highlighting
Fenced code blocks are automatically processed by Prism.js. Languages supported are the default languages in the Prism.js bundle. For syntax highlighting you have to include a Prism.js style in your index.html
.
Using with GitHub Pages
You can use Gumdrop with GitHub Pages as it can serve as a static file server. To prevent GitHub Pages from trying to transform your site with Jekyll add an empty .nojekyll
file to the root of your site.
Contributing
All ideas, recommendations, bug reports, pull requests are welcome. 😄