2.2 config.toml

The config.toml file is used by Books.jl. Settings in this file affect how Pandoc is called. In config.toml, you can define multiple projects; at least define projects.default. The settings of projects.default are used when you call pdf() or serve(). To use other settings, for example the settings for dev, use pdf(project="dev") or serve(project="dev").

Below, the default configuration is shown. When not defining a config.toml file or omitting any of the settings, such as port, these defaults will be used. You don’t have to copy all these defaults, only override the settings that you want to change. The benefit of multiple projects is, for example, that you can run a dev project locally which contains more information than the default project. One example could be where you write a paper, book or report and have a page with some notes.

The meaning of contents is discussed in Section 2.2.1. The pdf_filename is used by pdf() and the port setting is used by serve(). For this documentation, the following config is used

[projects]

  [projects.default]
  contents = [
    "about",
    "getting-started",
    "demo",
    "references",
  ]
  output_filename = "books"

  # Full URL, required for the sitemap and robots.txt.
  online_url = "https://huijzer.xyz"
  online_url_prefix = "/Books.jl"

  # Extra directories to be copied.
  extra_directories = [
    "images",
    "files"
  ]

  port = 8012

  [projects.notes]
  contents = [
    "demo",
    "notes",
    "references"
  ]

  # This project is only used when testing Books.jl.
  [projects.test]
  contents = [
    "test"
  ]

  online_url = "https://example.com"
  online_url_prefix = "/Example.jl"

Which overrides some settings from the following default settings

[projects]

  # Default project, used when calling serve() or pdf().
  [projects.default]
  homepage_contents = "index"

  metadata_path = "metadata.yml"

  contents = [
    "introduction",
    "analysis",
    "references"
  ]

  # Output filename for the PDF.
  output_filename = "analysis"

  # Full URL, required for the sitemap.
  online_url = "https://example.com"

  # Prefix for GitHub or GitLab Pages.
  online_url_prefix = ""

  # Port used by serve().
  port = 8010

  # Extra directories to be copied from the project root into `_build/`.
  extra_directories = []

  # For large books, it can be nice to show some information on the homepage
  # which is only visible to online visitors and hidden from offline users (PDF).
  include_homepage_outside_html = false

  # Syntax highlighting.
  highlight = true

  # Alternative project, used when calling, for example, serve(project="dev").
  [projects.dev]
  homepage_contents = "index"

  metadata_path = "metadata.yml"

  contents = [
    "introduction",
    "analysis",
    "notes",
    "references"
  ]

  output_filename = "analysis-with-notes"

  port = 8011

  extra_directories = []

  include_homepage_outside_html = false

Here, the extra_directories allows you to specify directories which need to be moved into _build, which makes them available for the local server and online. This is, for instance, useful for images like Figure 1:

![Book store.](images/book-store.jpg){#fig:book_store}

shows as

2.2.1 About contents

The files listed in contents are read from the contents/ directory and passed to Pandoc in the order specified by this list. It doesn’t matter whether the files contain headings or at what levels the heading are. Pandoc will just place the texts behind each other.

This list doesn’t mention the homepage for the website. That one is specified on a per project basis with homepage_contents, which defaults to index. The homepage typically contains the link to the generated PDF. Note that the homepage is only added to the html output and not to pdf or other outputs.

2.2.2 Website landing page

By default, Books.jl assumes that you will want a separate landing page for your book when you host it. This page is not added to the generated outputs, like PDF, so it’s a nice place to put links to the generated outputs. You will need to create a index.md file in the contents directory. Then, using an top-level header from Markdown (e.g. “# Title”), give the file a title. Immediately after the title, you need to write {-} to avoid this chapter showing up in your HTML menu.

Here is an example of how an example index.md file looks like:

# My Book's Awesome Title! {-}

Welcome to the landing page for my awesome book!