Neanderthal NPM

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

Open the posts/ directory in your neanderthal project.
Create a new folder with the URL for your post, e.g. "learning-git".
Add an index.md file with the content from posts/template/index.md.
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