DesignWithFontForge.com: a free book on type design, and the Jekyll site behind it

A book, not a tool, and what that means for a reader

The designwithfontforge.com repository is a book project about how to design new typefaces with FontForge. That is the whole subject, and the project is unusually clear that it is a book rather than a tool, a website rather than a program.

For a reader, the useful consequence is that the content is structured rather than a collection of forum answers. The site is at designwithfontforge.com, and after reading it the project points you to the FontForge users mailing list on SourceForge, describing it as an excellent place to find prior information, ask questions, or discuss the book, the fonts, or how to use FontForge. The division of labour is sensible: the book teaches the craft, the mailing list handles the specifics.

The project also has a specific audience for its content. The topics in the repository are book, fonts and how-to, and the site has a per-language weight list mechanism, which is a signal that the book is expected to be translated and that a translation has to keep a page in the same position in the sidebar as the original.

Eight language editions are present in the repository. Alongside the default en-US there are de-DE, fa-IR, fr-FR, ja-JP, pt-BR, zh-CN and zh-TW, and each has its own weight list file at the top level, for example en-US-weightlist.md and zh-CN-weightlist.md, with the language directories themselves sitting alongside.

The book and the site are licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported Licence, which is the right licence for this kind of work: it lets anyone reuse and translate the book, provided attribution is given and derivatives are shared under the same terms. The repository's own licence field is listed as unknown, so the stated Creative Commons terms in the README are the ones to rely on.

How the pages are ordered, and the weight list contract

The site is a Jekyll site hosted on GitHub pages, and the default branch is gh-pages. The README points contributors at the gh-branch for the project files, and the repository root contains the site source: the _layouts, _includes, assets, _config.yml and the language directories.

Every page is a Markdown file with a .md extension, and the ordering of the book comes from front matter rather than from filenames. The documented fields are:

    ---
    published: true
    layout: bookpage
    category: Workflow
    weight: 3
    title: Page Title
    ---

published controls whether the page appears, layout names the template and bookpage is the default, category groups the page, weight is an integer that affects the ordering in the sidebar and the homepage lists, and title sets the page title used in the title tag and the h1.

The weight system has its own rules, and they are stated because contributors break them otherwise. If a chapter or page is added or removed, update the corresponding list. If the new chapter falls between existing chapters, add a weight between the existing weights. If it comes after any existing chapters, add the weight number by 3, which is the convention for leaving room to insert later. If no more full numbers can be added between the existing weights, start using decimals. And only edit the weight list for your own language.

The example given in the documentation shows the resulting table, with weight 0 for the index, 1 for the introduction and 3 for What Is a Font, and the gap of 2 between 1 and 3 is exactly the space the add-by-three rule preserves.

Running the site locally with Jekyll

The build instructions are concrete. On Linux you need ruby-dev installed, and the example given is for Ubuntu 24.04:

sudo apt-get install ruby-dev

Then Jekyll is installed:

sudo install jekyll

To see the site as it will appear after processing and review your edits live in a browser, you go into the directory where _config.yml lives and run:

jekyll serve --watch
# or
jekyll serve --livereload

After that you browse http://localhost:4000/. The two flags are the difference between a rebuild on change and a rebuild with the browser refreshing itself, and for a book where you are editing prose and checking how it reads in the layout, the livereload variant is the one that saves the most time.

The directory layout is documented so a contributor knows where to put things. The _layouts directory holds the HTML template files, the _includes directory holds snippets of HTML included in pages and templates, the assets directory holds CSS, JS and some image files, the _config.yml is the Jekyll configuration, and the en-US directory holds the site's contents in US English, which is the default. There is also a subdirectory en-US/images/precompressed/ for the original, pre-compressed content images.

So the workflow is a static site with a watch server, a Markdown file per page, and a front matter block that decides where the page lands. Beyond Jekyll there is the Grunt image step and the ebook build.

Compressing the images with Grunt

The image step is a separate build stage, and it exists because a type design book carries a lot of illustrations. The raw images go into en-US/images/precompressed/, and the compressed versions end up in en-US/images/.

The tooling is npm and Grunt, and the package manifest shows a deliberately small dependency set: grunt at 1.0.1 or newer, grunt-notify for the desktop notifications that tell you the job finished, grunt-contrib-imagemin and imagemin at 4.0.0, and vinyl-fs for the file handling. There is a Gruntfile.js at the repository root and a package-lock.json alongside the package.json.

The sequence is npm install to pull the dependencies, then grunt to minify the images, and then you wait for Grunt to notify you before the compressed images appear in en-US/images/.

Two details are worth noting for a contributor. The grunt-notify dependency exists purely for that notification, which is the only feedback loop you get from a long image minification pass. And the separation into precompressed and images directories means the source images are kept in the repository, so a contributor editing a figure drops the new original into precompressed/ and lets Grunt regenerate the served version, rather than replacing the compressed file by hand and losing the pipeline.

The step is also the one that needs the most local setup, since it needs Node and npm where the Jekyll serve step needs Ruby, so a contributor working on both text and figures ends up with two toolchains installed.

Building the ebooks, and the parts of the repo you do not touch

The last build artefact is the ebook, and its script is the most involved of the three because it needs external document tools rather than just a language runtime:

sudo apt-get install calibre ghostscript
cd ebook
npm install
./create_books.sh

Calibre is the ebook management tool and ghostscript handles the PostScript and PDF work that font rendering implies, and both are installed with apt before the script runs. The ebook directory has its own package.json, so the npm install there is separate from the Grunt one at the root, and the create_books.sh script is what ties them together.

The repository root is broader than the English book, and the directory listing makes the structure clear. Alongside the language directories and their weight lists there is an index.html at the root, a CNAME file for the custom domain, a favicon.ico, an assets directory, the Gruntfile.js, a params.json, and people files, AUTHORS.txt and CONTRIBUTORS.txt. The ebook directory holds the generation script.

The ebook step is worth understanding as a distinct deliverable rather than a nicety. A book about drawing typefaces needs to be readable as a book, not only as a website, and the PDF and ebook pipeline is what turns the Markdown and images into something you can read offline or on a device where a browser is inconvenient. The Calibre and Ghostscript requirement is a fair signal that this is a real typesetting step rather than a markdown-to-epub conversion.

The contributing guidance is the other thing the README is explicit about. There are three routes: report an issue for someone else to resolve, contribute a change directly by forking the repository and editing the plain text files and sending a pull request, with a short how-to linked for people who find that unfamiliar, or discuss general topics on the fontforge-devel email list.

Editorial conclusion

This book suits a type design beginner who wants a structured path through drawing glyphs in FontForge rather than scattered tutorials, and it suits a translator or an educator who wants to bring the book into another language, since the site is designed for parallel editions. It is a poor fit if you need a reference on FontForge's interface, since the documentation is about type design practice rather than the software's features, and a poor fit if you need the code in this repository, since the FontForge parts live elsewhere. Before contributing, read the weight list rules for your language, keep the Markdown front matter fields intact, and check the file naming and chapter structure of the edition you are editing.

Frequently asked questions

Official sources

1. fontforge/designwithfontforge.com on GitHub
2. Issues
3. Project website
4. README