Gitbook Static Site

This intends to be an readme-documented, open-source-licensed, semantic-versioned, conventional-committed and changelogged git repository starting point for the publication of a gitbook static site

A straightforward beginning for a Honkit's Gitbook SSG repository

Beside brings Gitbook file system structure and useful Makefile targets to help development process, it also provides deploy-on-push automation through github action.

Check published book result example

Table of Contents

See all

• Getting started
  • Development environment
  • Repo publication
• Project specifications
  • Features
  • Folder structure
• Maintenance
• License

Getting started

First of all, from this template,
Name it accordingly and place where it best fits for your team.

Development environment

Make sure you have Git, Make and NPM installed:

$ git --version
git version 2.25.1
$ make --version
GNU Make 4.2.1
$ npm --version
7.11.1

Thus, clone the recent-created repository locally, and set up its development environment:

$ make init

Finally, you are ready to write your Gitbook first chapter and proceed to publish it.
You would like to check if defined plugins fit all your needs, changing it in book.json and package.json accordingly

Continuos deployment

You need to enable Github Pages in repository setting. For that, choose the root of repo's gh-pages branch and you are setup

Repo publication

After all, you should make this project your own:
Write a good README to present your project to the world.
And also ensure to tailor the project license to your needs.

Project specifications

Here some descriptions about this template project:

Features

This project shortens a repository start setup, considering:

• Inclusion of mature README document, inspired by [Standard Readme][>1]
• Inclusion of open-source LICENSE file
• Inclusion of structured, yet raw, CHANGELOG file
• Compliance with widely-used version control conventions, such as:
  • Semantic Versioning
  • Conventional Commit
  • Keep a Changelog

It also powers up development workflow by:

• Inclusion of a preset book.json configuration file
• Usage of package.json to plugins dependencies setup
• Inclusion of proficient Makefile that improves development management
• Inclusion of appropriate .gitignore file
• Pre-configured Github Pages publication workflow

Folder structure

.
├── .git/                       Version control system folder
├── .github                     Github repo's configuration directory
│   └── workflows               Continuous integration settings
│       └── deploy.yml          Deploy-on-push automation descriptor
├── .gitignore                  Ignored files manifest
├── book/                       Gitbook source directory
│   ├── HOME.md                 Site home page
│   └── SUMMMARY.md             Site left menu link list
├── book.json                   Gitbook configuration file
├── CHANGELOG.md                Release notes description
├── LICENSE                     License file
├── Makefile                    Development management facilities
├── package.json                Node dependency descriptor
└── README.md                   Readme document

Maintenance

This project is maintained by the author, @artu-hnrq.
It has reached a stable, usable state and is being actively developed.

License

This project is published under the permissions established by GNU General Public License v3.0.