paper-fish v0.5.23
paper-fish
Create a static blog from markdown (or other markup languages) files (+ metadata) hosted on Github.
It currently runs: https://newfivefour.com/
Features:
- Can deal with other markdown languages - not just markdown
- Tags and tag categories
- Pagination
- An atom/RSS feed
- A sitemap
- Automatic date creation from git modification times
- Ability to add metadata to posts to use in your blog
- Complete control over the HTML output
paper-fish
comes with a very basic HTML default. You'll immdiately want to change this by modifying the javascript files.
Example of a blog post hosted on github
The files are markdown with some metadata headers. Each file is like this:
title: The title
tags: misc,hello
someothermetadata: hello
date: Mar 11 2001
Here's some *normal* markdown
Note the date
metadata is optional. If it's not there we'll get it from github.
All your metadata will be available in the output posts. And you can aggregate all the metadata too.
Usage
Create a Github repository like this: https://github.com/newfivefour/test-paper-fish-posts
Go to https://github.com/settings/tokens and create an access token with repo access.
Create a blogconf.json
file like this:
{
"githubNameAndRepo": "YOUR_GITHUB_USERNAME/YOUR_REPO",
"githubAccessToken": "YOUR_ACCESS_TOKEN",
"websiteUrlForFeeds": "www.whatever.com/",
"feedTitle": "This will appear in atom.xml",
"outputDir": "output/",
"paginationValue": 3
}
(Note: the url and the output dir must end with a /
)
- Run
npm -g install paper-fish
- Make the
output
directory in your filesystem - Run
paper-fish
Your blog will now exist in the output/
directory, with the sitemap and atom feed.
Structure of the blog
The blog will have an index.html
page and will have five posts on it, if your pagination value is five. index.2.html
will have the next five posts on, and so on.
For each tag, a category page will be built. If you have a tag sometag
then category_sometag.html
will be created with five posts on it, if your pagination value is five. category_sometag.2.html
will contain the next five posts.
A single page file will be created for each file. If you have a file somepost.md
, then a somepost.html
file will be created.
The posts are ordered by date. This comes from either the date
metadata field in the post (pased by javascript's Date
function) or from the lastest git commit date for that file.
A atom.xml
RSS feed and a sitemap.xml
sitemap is also created.
Understanding how to modify the HTML output
Your blog will be created with the default styling. You'll want to change that.
The current file that controls that is in your npm global directory. It relates to https://raw.githubusercontent.com/newfivefour/paper-fish/master/lib/paper-fish-default-output.mjs
export const singlePost = (post, allPosts) => `
...
`
export const taggedPaginatedPosts = (tag, index, indexEnd, pagePosts, allPosts) => `
...
`
export const mainPaginatedPosts = (index, indexEnd, pagePosts, allPosts) => `
...
`
The first method controls a single post html file, the second method controls the "category_tagname.html" pages, and the third controls the "index.html" pages.
The parameters:
- index - this starts from 1, and is the pagination value of the page
- indexEnd - if you have 8 pages, this value will be 8
- post - this is a post object
{ path: "originalfilename.md" content : { headers: { title: "Title", tags: ["a", "b"], date: "Mar 1 2001" }, text: "markdown text" } }
- pagePosts - array of posts object for this pagination page, e.g. if you have a pagination value of 3, they'll be three posts
- tag - if you have a post tagged
hello
, then the value will behello
. - tags - given to the
mainPaginatedPosts
method as a convienence: a list of all the tag in frequency order,{ tag: "name", freq: 7 }
for example - allPosts - this is a list of all the
post
objects that exist in your github repo sorted by date - can be used to extra custom metadata from all the posts
Specifying a markup language other than markdown
In the custom HTML output javascript file, we specify the markup language parser to use.
The default style uses markdown, but you're free to use whatever.
In the HTML output javascript file we do something like this:
import * as markdown from 'markdown'
const parseText = markdown.default.parse
...
${parseText(post.content.text)}
...
Customising the output
Let's say you've decided to make your output file, personal_output.mjs
- below is very basic.
import * as markdown from 'markdown'
const parseText = markdown.default.parse
export const singlePost = (post, allPosts) => `
${parseText(post.content.text)}
<hr>
${post.content.headers.date}
<hr>
${post.content.headers.tags.map(t => t).join(" | ")}
`
export const taggedPaginatedPosts = (tag, index, indexEnd, pagePosts, allPosts) => `
<h1>${tag}</h1>
${pagePosts.map(p => `<h3>${p.content.headers.title}</h3> ${parseText(p.content.text)}`).join("<hr>")}
<hr>
Page ${index} of ${indexEnd}
`
export const mainPaginatedPosts = (index, indexEnd, pagePosts, allPosts) => `
<h1>Your blog</h1>
${pagePosts.map(p => `<h3>${p.content.headers.title}</h3> ${parseText(p.content.text)}`).join("<hr>")}
<hr>
Page ${index} of ${indexEnd}
`
Then you can specify it in your blogconf.json
file as outputMJSFile
. The path must be absolute:
{
...
"outputMJSFile": "/the/full/path/personal_output.mjs"
}
Now run paper-fish
in the directory and you will have a blog with custom output.
Testing
npm test
for the unit tests.
npm run ui-test
for the UI tests -- but you'll need to supply a blogconf.json etc for them to work and have firefox in /usr/bin/firefox
TODO later
- Talk about github api and api call interval
- Make it so you don't need .md for the github files
- What if output filename is wrong?
- Specify config file from command line
- Use output html files on github
- Use latest packages on live
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago