Franklin is a static-site framework, optimized for online books.
Franklin is built on top of Middleman, a fantastic static site generator written in Ruby. The setup steps are as follows:
1) Install Dependencies
Ensure that you have the following installed:
- Ruby (comes pre-installed on Mac)
- Rubygems (comes pre-installed on Mac)
- Bundler (see http://bundler.io for installation instructions)
2) Install Middleman
# Run the following commands in the console gem install middleman
For more detailed instructions, see http://middlemanapp.com/basics/getting-started/.
3) Download this project, and place it in your ~/.middleman directory:
# If you have git installed... git clone firstname.lastname@example.org:bryanbraun/franklin.git ~/.middleman/bryanbraun/franklin
4) Create your project:
# Replace 'mysite' with the name of your project middleman init mysite --template=bryanbraun/franklin cd mysite bundle install # Installs any franklin-specific gems.
The most basic purpose of Franklin is to convert a stack of markdown files into an HTML site, and to do it in a way that is optimized for books.
Your markdown files go into the "source" folder. They can be named anything (
xxxxxxxx.md), except you must have a file named
index.md to serve as the front page of your book. Franklin starts you out with some example files, which you can change or remove to suit your needs.
The structure of your book, as given in the Table of Contents, will mimic the structure of the markdown files in the source directory. Notably:
- Your front page (
index.md) will be promoted to the top of the list.
- Pages will be ordered alphebetically by their file names (thus, using a numbered prefix, like
- Your readme (
readme.md) file will not appear in your table of contents (for guidence on how to exclude other items from the Table of Contents, see the README for the Middleman-Navtree gem).
When you are ready to build your site, run the following command:
# This creates a `build` folder, containing your site, converted into static HTML. bundle exec middleman build
Using Middleman's customization options, you can do all sorts of interesting things beyond this basic use-case. For details, see the Middleman documentation.
This is where you can change the author, title, and other book information. The available parameters are (with example values):
title: Example Book author: You github_url: https://github.com/yourname/example-book domain: http://yourname.github.io/example-book license_name: Attribution-ShareAlike license_url: https://creativecommons.org/licenses/by-sa/4.0
This defines the order and structure of your book (for the table of contents and pagination). This file is generated automatically and should not need adjustment. For advanced use-cases where adjustment is desired, see the middleman-navtree docs (specifically the
Themes can be found in the
source/themes directory. You can use your own theme by adding it to the
themes folder and changing the value in
config.rb: like so:
config[:theme] = 'glide'
Any theme you add must have the following structure:
The main page layout is defined in
layouts/layout.erb. For more details on working with layouts, see Middleman's documentation.
Default locale is
:en. If you want to change it, for example to
:pl, configure middleman:
activate :i18n, :mount_at_root => :pl
and put locales file
locales directory in format:
--- pl: previous_page: 'Poprzednia' next_page: 'Następna' table_of_contents: 'Spis treści'
- Fork this project
- Create a feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Add some feature')
- Push to the branch to github (
git push origin my-new-feature)
- Submit a Pull Request
(If you are making a contribution, add your name here as part of your pull request)