jekyll-book-framework

Publish and write a book

A jekyll framework for publishing book in multiple format (HTML, PDF, epub)

Documentation | Demo | Contributing

_{Built with ❤︎ by Michael Ravedoni and contributors}

Table of Contents

• Introduction
• Features
• Usage
• Deployment
• Documentation
• Contributing
• Release History
• Authors and acknowledgment

Introduction

This tool is inspired by Antoine Fauchié's excellent thesis (Vers un système modulaire de publication : éditer avec le numérique). The project on which his thesis was based served as the basis for the development of jekyll-book-framework.

To get an idea, you can see the demo of this project.

Features

• Markdown writing format
• PDF auto generation with paged.js
• Static site generator with Jekyll
• Clean interface

Usage

Clone the project using git:

git clone https://github.com/michaelravedoni/jekyll-book-framework.git
cd jekyll-book-framework

Or, download manually : Download the project and unzip it. Once done:

1. Rename the directory with the name you want. For example: my-book (JEKYLL-BOOK-NAME in the following steps).
2. Edit the configuration file (_data/meta.yml) as needed.
3. Edit the stylesheet variables located in book/styles.
4. Edit the book/work content files located in book/text.
5. Install the dependencies, start and deploy the project (see below).

Install

To run the project, you have to install Jekyll (and therefore Ruby). Also install npm if you want to easily deploy the FTP life application (see deploy) or to easily run the project.

After you install Ruby, install the Jekyll CLI:

$ gem install jekyll bundler

Enter in your project's folder:

cd JEKYLL-BOOK-NAME

Install all Ruby and npm dependencies, such as Jekyll and plugins:

bundle install
npm run install

Start

To start and serve the project for development, run:

npm run dev

Preview your local book in your web browser at http://localhost:4000.

To build the component for production, run:

npm run build

Deployment

At some point you will probably want to publish what you have built so that it can be shared with the wider world. The projects currently supports three methods of deployment: Netlify, Github Pages and Rsync.

Netlify

Assuming you have created a repository for this project on GitHub, sign up or log in to Netlify using your GitHub account.

1. Click the big button labeled new site from Git
2. Select your repository
3. Configure the basic build settings: choose appropriate branch (master by default)
4. You can set the default build command to jekyll and the publish directory to _site/, but this is not necessare since the netlify.toml file has all the information pre-configured.
5. Netlify will auto-generate a site URL for you, or you can set it yourself. The default example uses http://JEKYLL-BOOK-NAME.netlify.com. Set this as your baseurl in _config.yml.
6. Now, every time you push up a commit to master on GitHub, Netlify will automatically rebuild your site using the settings in netlify.toml. Pretty cool!

GitHub Pages

Unlike Netlify, GitHub Pages does not support continuous deployment. This means you will need to manually deploy the site by running a script provided in bin/github-deploy.sh in the project folder.

1. In _config-github.yml, set the baseurl in the format that GitHub Pages expects (https://yourusername.github.io/JEKYLL-BOOK-NAME for most sites).
2. At this point you can run bin/github-deploy.sh and everything will be pushed up to GitHub on the gh-pages branch:

npm run deploy-github

It may take a few moments for everything to become visible online. If you get git errors when deploying because of upstream changes, you can always delete the gh-pages branch on GitHub and re-run the deploy script.

If you want, you can remove the _site directory from your .gitignore file so that you can check built files into version control.

Via FTP (RSync)

Any web server capable of hosting static files will work (S3, FTP server, etc.). For deploying the site via FTP (RSync), follow this instructions. In the main project folder /, run (if not already done) :

npm install

Rename the env-model.json file in env.json and open-it. Then fill the <user>, <host> and <path/> with your FTP remote server informations. For example:

username_example@example.ftp.com:web/JEKYLL-BOOK-NAME/

Then, to deploy the app, run :

npm run stage            #For testing on your test server
npm run stage-dry        #If you want to run a dry test

npm run deploy-rsync     #For the production server
npm run deploy-rsync-dry #If you want to run a dry test

Documentation

Architecture

• data/meta.yml: Contains all the metadata of the project and the book. Change the variables on your needs.

• book: Contains all the contents of the book. book/text contains all the markdown files. If you have a translation, book/fr contains the translated book.

• index.md: Home page of the book (editable)

• _bibliography: Contains the bibliographys in BibTex format (.bib file) necessary for the jekyll-scholar plugin

• materials: Directory containing all the files (image, text, media) and drafts of the book for discussion

• images: Directory containing the files and images necessary for the book

• output : Directory containing the output formats of the book

• _includes, _layouts, _sass, _plugins and others: Files necessary for the working of Jekyll

All the files and directories can be modified for customization and your own needs.

Branches

For each development or writing idea, we recommend creating a specific branch in your project. This will facilitate project discussions and monitoring.

Commits format

To make the use of Git more understandable, here is a list of conventions for writing commits:

• admin : technical management of the repository or site
• style : styles
• edit : content edition
• fix : correction, modification following a remark
• org : organization of files, repository, site
• gen : automation for the generation of the different files and formats
• test : test (but normally reported in a specific branch)

Contributing

We’re really happy to accept contributions from the community, that’s the main reason why we open-sourced it! There are many ways to contribute, even if you’re not a technical person.

1. Fork this project
2. Create your feature branch (git checkout -b feature/fooBar)
3. Commit your changes (git commit -am 'Add some fooBar')
4. Push to the branch (git push origin feature/fooBar)
5. Create a new Pull Request

Release History

You will find the releases history in the release section. For more detail, you can check the changelog.md file.

Roadmap

• Styles and css restructuration
• i18n
• auto pdf genarator
• epub, mobi and markdown export
• create different work layouts
• define a workflow (version, edition, translation)
• create template for git issues (Github and GitLab)
• create deploy command for GitLab

Authors and acknowledgment

• Michael Ravedoni - Initial work - michaelravedoni
• Antoine Fauchié - Inspirated work and project - antoinentl

See also the list of contributors who participated in this project.

• electric-book - Inspiration - Electric Book Works
• Quire - Inspiration - Getty Publications

License

MIT License