Configuring a blog is annoying, let's do better.
markdown-it to transform Markdown into HTML (post.html in templates).posts in templates).front-matter to set nunjucks filters in templates for string processing.front-matter to nunjucks templates under fm key (post.fm.title).front-matter for RSS feed metadata.feed.sitemap.txt from contents.npm i upwrite
Assuming you've completed the setup, using the CLI:
upwrite [options]
Or using the API:
const upwrite = require('upwrite');
upwrite(options).then(done).catch(err);
| Key | CLI shortcut | Default | Description |
|---|---|---|---|
input | -i | posts/ | Directory where your content to be transformed exists. More |
output | -o | _site/ | Directory where the final output should be written. More |
rss | -r | feed.json | The .json file which informs the RSS feed also indicates the working directory. More |
template | -t | templates/post.njk | The nunjucks template to use for the transformation. More |
copy | -c | true | Copies non-markdown files into the output directory in the same structure. More |
CLI options example:
upwrite -i blog -o public -r rss.json -t nunjucks/blog.html
blog/ directory for files.public/ directory; creating public/blog/rss.json file to initialize the feed. Writes public/rss.xmlnunjucks/blog.html📁 ./
├── 📁 _site
├── 📁 posts
├── 📁 templates
└── 📄 feed.json
_site/ directory will be created during upwrite execution.posts/ directory holds .md files with front-matter.templates/ directory holds .njk files for use with nunjucks.feed.json file has initial feed information.Each post is a .md file with front-matter at the top with metadata expected to populate the RSS feed. The metadata is piped into the addItem() method of the feed project.
---
title: My first post
description: And I think you all should read it
date: 2013-12-29 17:16:55
---
If you want the post to be rendered within the RSS feed, you must include the date field. To render without including in the RSS feed, omit the date field.
You may include a special template key to override the base template for specific posts.
---
title: My second post
description: You should all still read it
date: 2022-03-11 07:16:55
template: templates/no-date.njk
---
Notice that the template key is expecting the path relative to the feed.json
The templates are transformed using nunjucks. Much of the data collected through processing is found on a post key within the file. You'll commonly have the following basic template setup:
<!doctype>
<html>
<head>
<!-- Any metadata found in the front-matter is at `post.fm` -->
<title>{{ post.fm.title }}</title>
<meta name="description" content="{{ post.fm.description }}">
</head>
<body>
<datetime>{{ post.fm.date }}</datetime>
<!-- Use the "safe" filter in Nunjucks to render `post.html` as html -->
<main>{{ post.html | safe }}</main>
</body>
</html>
The ability to filter incoming data is important in nunjucks. You can prepare front-matter-like filters at the top of your entry template to include filters for your nunjucks environment. This can only occur in the templates referenced within the transformation (either the template key in the options, or the template key in a .md front-matter). The process cannot read front-matter added to files that are
included along the way.
---
humandate: (date) => new Date(date).toDateString()
---
<!doctype>
<html>
<head>
<!-- front-matter cannot be parsed in the head.njk file -->
{% include "head.njk" %}
</head>
<body>
<!-- Use the "humandate" filter created in the front-matter above -->
<datetime>{{ post.fm.date | humandate }}</datetime>
<main>{{ post.html | safe }}</main>
</body>
</html>
You can generate navigation using the different keys injected into each page.
<!doctype>
<html>
<head>
<!--
page are the keys found in feed.json.
post.fm are the keys written in the .md front-matter
-->
{{ page.title }} - {{ post.fm.title }}
{% include "head.njk" %}
</head>
<body>
<nav>
<ul>
<!--
Using item to indicate the posts in the loop versus this current post.
We only want entries that do NOT have a date.
These are static pages (like 'home' or 'about').
You can also sort by giving these pages additional front-matter to sort by.
-->
{% for item in posts %} {% if not item.fm.date %}
<li>
<a href="{{ item.pathname }}">{{ item.fm.title }}</a>
</li>
{% endif %} {% endfor %}
</ul>
</nav>
</body>
</html>
| parent | keys | definition |
|---|---|---|
page | { title, description, url } | Data direct from feed.json |
posts | [{ fm, html, pathname, link }] | Represents all posts as an array of post objects |
post | { fm, html, pathname, link } | Represents this post with the front-matter (fm) and markdown rendered as HTML (html) |
The pathname is the relative path to the post. The link is the absolute path to the post.
feed.jsonThis .json file is the starting point to create the RSS feed. It has the following required fields:
{
"title": "The best blog",
"description": "The one and only",
"link": "https://example.com"
}
The link field is especially required as it's used to construct post urls alongside the file structure of your project. The name of this file (feed) is used to name the resulting .xml file of the feed (feed.xml) and can be changed in the options.
The path to the feed.json also sets the base of your working directory. This allows you to change where all the other filepaths start from.
await upwrite({
rss: 'website/feed.json',
input: 'posts', // actually at website/posts
output: '_site/', // actually at website/_site
template: 'post.njk', // actually at website/post.njk
});
📁 ./
└── 📁 _site
├── 📄 feed.xml
├── 📄 sitemap.txt
└── 📁 posts
└── 📁 [markdown-filename]
└── 📄 index.html
feed.xml file is your RSS feed based on feed.json and the .md files found in the posts/ directory.sitemap.txt is a list of all the urls processed by the transformer, used as a sitemap.posts/ directory in _site/ will maintain the same structure of the source .md files but write index.html files instead of [markdown-filename].html. This allows for clean urls.- https://example.com/posts/first-post.html
+ https://example.com/posts/first-post
- https://example.com/posts/nested/third-post.html
+ https://example.com/posts/nested/third-post
All files found within the input directory that are not .md will be copied to the new directory using the same structure they were found with.
- ./posts/nested/media.jpg
+ ./_site/posts/nested/media.jpg
You can skip this by setting copy to false.
FAQs
Configuring a blog is annoying, let's do better.
We found that upwrite demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.
Security News
The Axios compromise shows how time-dependent dependency resolution makes exposure harder to detect and contain.