neanderthal

A static hypertext generator for your blog or website.

Overview

Neanderthal transpiles structured Markdown and Nunjucks content to a static blog, with support for custom pages, tagged posts, and authors. You can write posts in Markdown with front matter metadata, then customize the Nunjucks templates as needed.

Features

• Blog posts with support for multiple authors.
• A full tagging system.
• Author profile pages.
• Custom pages.
• Full support of the CommonMark Markdown spec, thanks to markdown-it.
• The power of Nunjucks templates.
• Incremental builds.

See the Changelog for a full project history.

Getting Started

The best-practice way to run Neanderthal is with npx. This will ensure you always use the version you started your project with. Run the below command to cache the current version of Neanderthal and set up a new project:

npm init -y
npx neanderthal

To serve the blog on a dev server with incremental builds, run:

npx neanderthal --serve

It's recommended to lock the version of Neanderthal you are using to your package.json file by calling

npm install --save-dev neanderthal

Now npx will run your project's cached installation of Neanderthal without polluting the global scope.

Documentation

Full documentation is (in progress) here. We plan on moving it to ReadTheDocs or something in the future.

Starting the Development Server

Run npx neanderthal -s to start a dev server on port 9080. Make changes to files and they'll recompile. Refresh the page and it will show your changes.

Making a new blog post

1. Open the posts/ directory in your neanderthal project.
2. Create a new folder with the URL for your post, e.g. "learning-git".
3. Add an index.md file with the content from posts/template/index.md.
4. Edit the frontmatter (the stuff between the dashed lines) to customize metadata for your post, then edit the markdown body.

Configuration in nconfig.js

Often the first file to edit, the more information you store in here will make your project more consistent.

meta

The meta object is sent to every Nunjucks template rendered in your site. You can add any information to this object you may need, such as the site name and organization. This object is available in any Nunjucks template in your entire project.

{{ meta.name }}

authors

You must choose a unique URL as the key for each author in the authors object. An author object must contain name,short_bio and bio fields but may contain any additional data. Common examples would be social media URLs that can be displayed in the author.njk template. Remember: any additional information passed into an author object is not rendered by default. You will need to access the data in the respective template.

config

The config object controls the build process. This is not yet implemented. TODO.

Templating

Neanderthal uses the wonderful Nunjucks templating system. Nunjucks is a Mozilla project designed to bring python's Jinja templating system to JavaScript. You can read the detailed Nunjucks templating documentation for more info.

Addendum

Help

If our docs don't suffice, ask for help on our Gitter. If you find a verifiable bug, please file an issue.

Contributing

We are looking for your help to make Neanderthal better! There is a general Roadmap for project, but feel free to open issues with new feature proposals.

Code of Conduct

Please read the project Code of Conduct.

Credits

This project would not exist without the following fantastic libraries:

• nunjucks - fully featured templating inspired by jinja2
• front-matter - extract meta data (front-matter) from documents.
• markdown-it - markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed
• fs-extra - adds file system methods that aren't included in the native fs module
• node-watch - a wrapper and enhancements for fs.watch
• highlight.js - javascript syntax highlighter
• ansi-colors - the fastest Node.js library for terminal styling engine for javascript
• server-handler - static server implemented by Vercel
• terminal-link - create clickable links in the terminal
• yesno - a nodejs library for issuing and handling responses to yes/no questions
• new.css - new.css is a classless CSS framework to write modern websites using only HTML.
• markdown-it-footnote - footnotes plugin for markdown-it markdown parser
• typescript - a superset of JavaScript, adds optional types to JavaScript