Working on this Book

This page covers the "workflow" around how to work with this site.

The site itself is a collection of static HTML, CSS, and Javascript pages, generated by mdbook. The "source code" for each page is a Markdown file. This is all stored in a Github repo.

mdbook includes a web server, meant for use while working on content. When you're working on the Markdown source files, it can show you what the finished site will look like, in a browser on your local machine. This works by running a simple web server and watching the source files. When it sees a file change whose contents affect the site, it sends a signal to the browser, telling it to reload.

ℹ️ Coordination

I've created the foks_book team on Keybase, and plan to use its "team chat" channel as a place for people to coordinate with each other and make sure we aren't duplicating each others' efforts.

If you're interested in working on this book, please join that team. If you have questions about FOKS that the book doesn't cover, also please join that team. Knowing what questions people are asking helps us to know what the book needs to cover.

Obviously, if FOKS adds a similar "chat room" functionality in the future, I'll create a team in FOKS and move the conversation there.

Repo Structure

The repo contains a collection of files which are involved in building the site. The files you'll be working with if you edit the book's content are:

• src/ - This directory contains the Markdown source files for every page.

• src/SUMMARY.md - This file contains the Table of Contents for the site, and is used to build the panel on the left. It is a markdown file, however it only supports a limited set of tags.

  If you're using mdbook's live preview feature, if you add a new page to the list in this file and save it, mdbook will create the associated Markdown file if it doesn't already exist.

• book/ - This directory contains the generated HTML, CSS, and other files which make up the rendered site. The book is "published" to a web server by copying this directory to the site's document root directory.

  This directory is not meant to be checked into the git repo, so it's listed in the repo's .gitignore file.

• book.toml - This file sets the overall properites of the book. This includes any custom steps to be performed in the rendering process.

This repo contains some customizations which aren't in normal mdbook books. These include a CSS stylesheet which adds horizontal lines above section headers (which I personally think makes it easier to read), as well as a script which is run during the rendering process to add the git commit information to the bottom of each page.

I do the same thing in a few dozen other "books" that I write and maintain. I created this repo to use as a starting point for new books, it contains more information about how the customizations work.

Pre-requisites

The only thing you really need in order to work on the site is a text editor.

Editorconfig

Your text editor should support Editorconfig. If it requires a plugin, it should be installed and enabled.

If your editor doesn't have a way to support editorconfig at all (such as nano), you should manually follow the rules laid out in the .editorconfig file, and use editorconfig-checker to check your files before committing them.

Live Preview

If you want to use mdbook's "live preview" feature, the following things will need to be installed on your workstation.

• mdbook - the program which reads the Markdown files and generates the HTML, CSS, and other files which make up the final web site.

• jq - a tool for working with JSON files. This is needed by the version-commit script, which sets things up to make mdbook include the commit information at the bottom of every page.

• A web browser, to preview the changes as you save them.

These are explained in more detail here, in the mdbook-template repo.

Workflow

This is the overall workflow to use while working on the book.

Setup

• If you haven't already, "fork" the repo into your own Github account. You'll be making your changes in your own copy of the repo.

  ⇒ Github Documentation - Fork a repository

• Make sure your fork is up-to-date with all commits from the main repo.

  ⇒ Github Documentation - Syncing a fork

• If you haven't already, clone your copy of the repo to your workstation.

  cd ~/git/
  git clone https://github.com/USERNAME/REPONAME foks-book
  

• cd into the directory where you cloned the repo, and make sure it's up to date with the Github repo.

  cd ~/git/foks-book/
  git fetch -p
  git checkout main
  git pull
  

• Create a new branch to contain the changes you're working on.

  This is not strictly required, since you're working in your own repo. I find it helps to work on different tasks in different branches, especially at $DAYJOB where I might be working on a dozen or more different things at the same time.

  cd ~/git/foks-book/
  git checkout -b new-branch-name
  

Edit

• If you want to see the live preview while you're working, run make serve (or the appropriate mdbook serve command). This will render the book from Markdown into HTML, start a web server on your workstation, and open a browser pointing to that web server.

  This web server normally listens on http://127.0.0.1:3000/, which means the pages it's serving will only be accessible from the same machine.

  The IP address and port number can be changed if needed. For example, if you make it listen on 0.0.0.0 (which is what make serve-all does), any machine which can access your workstation will be able to view the pages. You will obviously want to be careful with this.

  Leave this command running while you're working.

• Edit the files under the src/ directory as needed.

  If you're using the live preview feature, visit the page(s) you're updating in the browser and make sure your changes are correct. Each time you save a file, the browser should automatically reload. (If you find this is not happening, manually reload the browser window and it should start automatically reloading again.)

Commit, Push, and Create a Pull Request

After you're happy with the proposed changes ..,

• If you're using the live preview feature, go back to the window where the mdbook web server is running, and hit CONTROL-C to stop it.

• Run editorconfig-checker to make sure the Markdown files are properly formatted.

  $ cd ~/git/foks-book/src/
  $ editorconfig-checker -v .
  ...
  0 errors found
  16 files checked
  

  If any problems are found, fix them before committing.

• Commit your changes and push the new branch to your repo.

  cd ~/git/foks-book/
  git add src/
  git commit -m 'Update information about XYZ'
  git push -u origin new-branch-name
  

  ℹ️ Commit Messages

  When your PR is merged into the main repo, your commits will become part of the main repo's history.

  I've seen dozens of different web pages claiming to tell you how to create a "perfect" commit messages. The important thing is that your commit messages should explain what they're doing.

  The other "rules" I follow, which are motly habits I've picked up over the years, are ...

  • Assume that the first line of the commit will have "This commit will" before it, and make it make sense.
  • If the commit message needs more detail than just one sentence, use multiple lines. Just make sure there's a blank line after the first line, since not including the blank line will confuse tools that other people might use.
  • Try not to use more than 72 characters per line. There are people who still use 80-column terminals.

  Commit messages don't have to be perfect, but they should be informative.

• The output from the git push command should contain a URL to create a pull request. Visit that URL to create a pull request.

  In the grey bar above "Add a title", make sure that ...

  • "base repository" points to the foks-proj/book repo
  • "base" points to main (the branch you want to merge into)
  • "head repository" points to your repo
  • "compare" points to the branch containing the changes in your repo

  ⇒ Github Documentation - Creating a pull request

Review and Merge

• At this point, other Github users will be able to see the pull request, and offer comments on it.

• If you want to update your proposed changes, create and push another commit to the same branch in your repo. When you push the new commit(s), Github will automatically update the pull request to include those changes.

• People can also "approve" the pull request. This simply means that they've looked over the changes and don't see any problems with them.

• When the repo owners decide that they're good with the changes, they can merge the pull request. This adds the commits from your branch, to the primary repo.

• Within a few minutes after this happens, the web site containing the rendered book will be updated automatically.

  ❗️ The mechanics of making this happen have not been set up yet.