Simple blog generator for hosting on GitHub Pages using Node and Asciidoctor.js.
This is a Jeykll/Hyde/Hugo copycat. It’s not nearly as extensible as Jekyll (yet!)
or as fast as Hugo (yet!). But if you don’t need a million themes to choose from
and you just want to deploy asciidoc to GitHub Pages as fast and easily as possible,
then this is the project for you. No adding front matter to your posts that messes
up your syntax highlighter, no learning Ruby or Go to understand what’s going on
if you’re just a humble Javascript/Node.js developer; just npm install blitzrk/
asciidoc-blog and you’re half way to a blog!
No longer is creating and asciidoc-blog tied to forking this repo. The process has been streamlined for easier install and updating.
$ npm install -g blitzrk/asciidoc-blog
$ mkdir blog
$ cd blog
$ ablog init
$ ablog server
Webserver started at http://0.0.0.0:8000ablog may also be installed locally and used either through npm scripts or at
./node_modules/.bin/ablog.
{
"scripts": {
"start": "ablog server",
"build": "ablog build",
"ablog": "ablog"
}
}Then
$ npm run ablog -- init
$ npm start
Webserver started at http://0.0.0.0:8000
^C
$ npm run build
...Now that that’s out of the way, you can create posts in _posts. Posts are just
normal asciidoc documents. Be sure to give it a proper header, though. To run a test
server, run ablog server and to build for production, run ablog build, which will
output your static site at dist/.
The header doesn’t have anything special added to it from the official specification.
= Title: Still Part of Title: Subtitle
Author Name <author@email.com>
v1.0.3, 1970-01-01 00:00: Comment
:toc:
:toc-title: Table of Doom
:toc-placement: preambleA title, author name, and date are all required, but adding the rest won’t break anything.
Currently there are two locations for configuring your site. Most options may be
found in config.json. Colors, however, are located in _assets/sass/_constants.scss.
Colors can be changed and will automatically update if you’re running the test
server (just refresh your page).
If "https" is set to true, then a provided script will be automatically run that redirects users to the https version of your site. (This must be set up separately. I will write a future post about it.) For testing purposes, it will only redirect if the host has no subdomain or a subdomain of www. This allows unsecure running of a test server with something like ngrok without messing up your configuration. To override this behavior, set "httpsSubdomain" to true.
There are a few options for deloying your site. However, my suggestion is to use Travis CI. That way you can even edit or create posts directly on Github.com and see them up on your site just a minute later without even opening up a terminal.
Obviously, the first step is to set up a Travis CI account.
Then you’ll want to turn on builds for your fork of blitzrk/asciidoc-blog. Next,
you’ll modify .travis.yml. This is pretty self-explanatory, except for the secure:
line. This is where you provide Travis with an encrypted version of your Github API
key.
So generate a new Github API key here with the
permissions for only public_repo. Then encrypt it with the travis CLI tool.
$ cd /path/to/blog
$ gem install travis
$ travis encrypt GH_TOKEN=<paste token from browser> --addThis has already added it to your .travis.yml file, so just commit, push, and it
will be built!
All that Travis does is run a simple script with some environment variables set.
You can do this, too! Either follow the steps in run/travis.sh, skipping where
appropriate (e.g. if you already installed/inited asciidoc-blog), or run
$ GH_NAME="<your name/Travis CI>" GH_EMAIL="<email>" GH_REF="github.com/<username>/<project>.git" GH_BRANCH="<gh-pages/master>" GH_TOKEN="<unecrypted token>" ./run/deploy.sh