Markdown is nice. And it’d be really nice to get documentation or some notes up there with just Markdown, right? GitBook lets us do just that.
From their website:
GitBook is a modern publishing toolchain. Making both writing and collaboration easy.
Here’s an example of a GitBook: Learn JavaScript.
GitBooks are however hosted on their own servers by default. If you’re like me and you’d like to keep everything in GitHub, here’s the way to go!
Creating your first GitBook
1. The GitBook CLI
1npm install -g gitbook-cli
Not sure what npm is? It’s a package manager for node. Installation instructions here.
2. Create a GIT repository
1git init gitbook-test
3. Create a new GitBook
1cd gitbook-test
2gitbook init
Update the contents of the README.md and SUMMARY.md files. Build and run the book using:
1gitbook serve
Make sure you add a .gitignorelike this one before making your first commit. If you’d like your pages to show up in the sidebar you’ll need to update SUMMARY.md accordingly.
Set it up with GitHub
Create a new repo on GitHub and push your commits to it. If you’re doing this for the first time, make sure you read everything that GitHub shows you so you understand what you’re doing.
To publish a Github site, you need to push the source files to a gh-pages branch. Let’s create that.
1git branch gh-pages
Let’s move to the newly created branch (gh-pages), push it to our Github repo, and come back to the original branch (master).
1git checkout gh-pages
2git push -u origin gh-pages
3git checkout master
Set up a gulp task to publish to GitHub Pages
First, create a package.json file using yarn.init. After that, run the following command to install required dependencies:
1yarn add gulp gulp-gh-pages gulp-load-plugins --dev
If you don’t have yarn installed you may install it using npm install -g yarn.
If you don’t have gulp installed globally run npm install -g gulp as well.
Create a new file called gulpfile.js and add the following code to it:
1const gulp = require('gulp');
2const gulpLoadPlugins = require('gulp-load-plugins');
3
4const $ = gulpLoadPlugins();
5
6// Publishes the site to GitHub Pages
7gulp.task('publish', () => {
8 console.log('Publishing to GH Pages');
9 return gulp.src('./_book/**/*')
10 .pipe($.ghPages({
11 origin: 'origin',
12 branch: 'gh-pages'
13 }));
14});
We can now publish changes to the site using:
1gulp publish
All we need to do is make sure we’ve run gitbook build or gitbook serve before that to make sure the _books folder has the lastest files.
Here’s a test repo I built using the above steps.