Muwu User Guide

4 Project Outline
4.1 Simple Outline
4.2 Nested Outline
4.3 Directed Outline
4.3.1 Contents
4.3.2 Multiple Documents
4.3.3 Metadata
4.3.4 Navigator
4.3.5 Subcontents
4.3.6 Text
4.3.7 Title
4.4 Headings and Filenames
4.4.1 Implicit
4.4.2 Explicit
4.4.3 Flexible
4.5 Case Sensitivity

4

Project Outline

The file outline.yml contains the project outline.

A project outline can be simple, nested, or directed.

4.1

Simple Outline

A simple outline contains a list of headings.

For example:

- Monday
- Tuesday
- Wednesday
- Thursday

In the example above, Muwu would look for the following files in the text/ folder:

monday.md
tuesday.md
wednesday.md
thursday.md

The heading in the compiled text will come from either the outline or the source file.

  • If the source file begins with a heading, Muwu will use the heading from the source file.
  • If the source file does not begin with a heading, Muwu will use the heading from the outline.

4.2

Nested Outline

To add subheadings or nested topics to an outline, end the heading with a colon, and indent the subheadings by two spaces.

  • Parent headings (ending with a colon) refer to subdirectories within the text/ folder.
  • Parent headings may also include their own optional source text.
  • Subheadings indicate a text file.

For example:

- Monday:
  - A trip uptown
  - Uncertain forecast
- Tuesday:
  - Gray skies
  - A gust of wind

In the example above, Muwu would look for the following files in the text/ folder:

monday.md
monday/a_trip_uptown.md
monday/uncertain_forecast.md
tuesday.md
tuesday/gray_skies.md
tuesday/a_gust_of_wind.md

If a parent heading lacks a corresponding source text file, Muwu will include the heading, as entered in the outline, and continue to the subheading.

4.3

Directed Outline

A directed outline unlocks all the features of Muwu. In addition to compiling text, Muwu can generate a table of contents, navigators between multiple documents, and sections for the project title and project metadata.

In a directed outline, the first-level outline headings are reserved for the following keywords:

  • contents
  • metadata
  • navigator
  • subcontents
  • text
  • title

The following discussion will develop the previous nested outline into a directed outline, beginning by making a text section from the previous nested outline, then building around it.

4.3.1

Contents

Single Text Section

After you declare a text block, you can add a table of contents by adding the contents keyword to the outline.

For example:

- Contents
- Text:
  - Monday:
    - A trip uptown
    - Uncertain forecast
  - Tuesday:
    - Gray skies
    - A gust of wind

In the above example, Muwu would generate a table of contents for the main (unlabeled) text section.

Multiple Text Sections

If an outline has multiple text sections, the contents keyword can specify the corresponding text section.

- Contents introduction
- Text introduction:
  - Forward
  - Dedication
- Contents
- Text:
  - Monday:
    - A trip uptown
    - Uncertain forecast
  - Tuesday:
    - Gray skies
    - A gust of wind

4.3.2

Multiple Documents

Insert a line containing three hyphens --- to separate the outline into multiple documents.

For example:

---
- Title
- Contents
---
- Text:
  - Monday:
    - A trip uptown
    - Uncertain forecast
---
- Text:
  - Tuesday:
    - Gray skies
    - A gust of wind

If a project has multiple documents, a contents section will include headings from all documents.

4.3.3

Metadata

The metadata keyword will generate a section that includes information from metadata.yml.

If the outline does not indicate which metadata values to include, Muwu will display all key-value pairs.

  • Unlike the title section, a metadata section displays both the key and its value.

For example:

- Title
- Metadata:
  - copyright
  - publisher
  - editor
- Contents
- Text:
  - Monday:
    - A trip uptown
    - Uncertain forecast
  - Tuesday:
    - Gray skies
    - A gust of wind

In the above example, the metadata section would appear as:

copyright
2013

publisher
Raincloud Books

editor
Kerry Kyles

Date of this edition

Using the phrase date of this edition in the outline as a metadata value will show the date on which the compiled text was created.

For example:

- Metadata:
  - date of this edition

would appear as

date of this edition
2018-10-07

4.3.4

Navigator

The navigator keyword will create the following links to move between multiple documents:

  • prev (previous)
  • home
  • next

If a project outline has multiple documents, Muwu will automatically generate navigator sections at the top and bottom of each document.

To generate navigator sections manually:

  1. Open the file options.yml.
  2. Change the option generate_navigators_automatically to false.
  3. Add the navigator keyword to the outline.

For example:

---
- Navigator
- Title
- Contents
---
- Navigator
- Subcontents
- Text:
  - Monday:
    - A trip uptown
    - Uncertain forecast
---
- Navigator
- Subcontents
- Text:
  - Tuesday:
    - Gray skies
    - A gust of wind

4.3.5

Subcontents

The subcontents keyword will build a table of subcontents only for the outline entries in enclosing document. Muwu will include the title of the project as a heading.

For example:

---
- Title
- Contents
---
- Subcontents
- Text:
  - Monday:
    - A trip uptown
    - Uncertain forecast
---
- Subcontents
- Text:
  - Tuesday:
    - Gray skies
    - A gust of wind

To generate a subcontents section automatically for each document with a text section:

  1. Open the file options.yml.
  2. Change generate_subcontents_automatically to true.

4.3.6

Text

Single Text Section

The text keyword indicates a set of headings and subheadings that refer to text files.

For example:

- Text:
  - Monday:
    - A trip uptown
    - Uncertain forecast
  - Tuesday:
    - Gray skies
    - A gust of wind

Multiple Text Sections

Multiple text sections can be used and given different names.

  • When using multiple text sections, an unnamed text section acquires a default name of main.

For example:

- Text introduction:
  - Forward
  - Dedication
- Text:
  - Monday:
    - A trip uptown
    - Uncertain forecast
  - Tuesday:
    - Gray skies
    - A gust of wind

In the example above, Muwu would look for the following files in the text/ folder:

introduction/forward.md
introduction/dedication.md
main/monday.md
main/monday/a_trip_uptown.md
main/monday/uncertain_forecast.md
main/tuesday.md
main/tuesday/gray_skies.md
main/tuesday/a_gust_of_wind.md

4.3.7

Title

The title keyword will generate a section to show the title of the project, as found in metadata.yml.

By default, Muwu will also look for the subtitle and the author.

For example:

- Title
- Contents
- Text:
  - Monday:
    - A trip uptown
    - Uncertain forecast
  - Tuesday:
    - Gray skies
    - A gust of wind

In the above example, the title section would appear as:

Distant Thunder

A Rolling Affair

Jove Moon

You can customize the title section by indicating which metadata values to include.

For example:

- Title:
  - title
  - author
  - copyright

4.4

Headings and Filenames

Muwu has three methods to find source files from the outline:

  • implicit
  • explicit
  • flexible

The default method is implicit. The preceeding outline examples used the implicit method.

To change the method:

  1. Open options.yml.
  2. Change the option outline_text_pathnames.

4.4.1

Implicit

With an implicit outline, the headings and topics in the outline indicate a path to the source files in the text/ folder.

  • Muwu will use lowercase letters for the filenames.
  • Numbers are allowed.
  • Muwu will convert non-word characters to underscores (_).
  • Muwu will add .md as a file extension.
  • Parent headings in the outline indicate a folder. Parent headings can also indicate an optional file.
  • Subtopics indicate a file.

For example:

- Text:
  - Monday:
    - A trip uptown
    - Uncertain forecast

The above example would imply the following filenames within the text/ folder:

monday.md
monday/a_trip_uptown.md
monday/uncertain_forecast.md
Haml option

If Muwu cannot find a source file ending in .md, it will also look for a source file file ending in .haml.

Muwu will give priority to Markdown files ending in .md.

Implicit Filenames with Multiple Text Sections

If your outline has multiple text sections with different names, the name of the text section indicates a folder.

  • An unnamed text section acquires a default name of main.

For example:

- Text introduction:
  - Forward
  - Dedication
- Text:
  - Monday:
    - A trip uptown
    - Uncertain forecast

The above example would imply the following filenames within the text/ folder:

introduction/forward.md
introduction/dedication.md
main/monday.md
main/monday/a_trip_uptown.md
main/monday/uncertain_forecast.md

4.4.2

Explicit

In an explicit outline, all parent headings and subtopics are the path to the file within the source folder.

  • Muwu will allow only word characters (a-zA-Z0-9_) in a filename.
  • Muwu will convert any non-word characters in the basename or extension to underscores (_).

For example:

Text introduction:
  - intro/forward.md
  - intro/dedication.md
Text main:
  - monday.md:
    - monday/a_trip_uptown.md
    - monday/uncertain_forecast.md

4.4.3

Flexible

A flexible outline combines features of the implicit and explicit methods.

  • Outline entries that do not end with .md or .haml indicate an implicit filepath.
  • Outline entries that do end with .md or .haml indicate an explicit filepath.

For example:

Text introduction:
  - intro/forward.md
  - intro/dedication.md
Text:
  - Monday:
    - A Trip Uptown
    - uncertain_forecast.md

The above example would indicate the following filenames within the text/ folder:

intro/forward.md
intro/dedication.md
main/monday.md
main/a_trip_uptown.md
uncertain_forecast.md

4.5

Case Sensitivity

Muwu has the following behaviors regarding upper- and lower-case letters.

  • When reading outline keywords, Muwu ignores case.

    text epilogue: will match teXt ePilogUe:

  • When searching for metadata keys and values, Muwu ignores case.

    title: will match Title:

  • When making implicit filepaths, Muwu uses lower-case letters.

    Monday: implies monday.md

  • When generating a text heading from outline.yml, Muwu preserves case.

    monDay generates monDay

  • When generating a metadata section, Muwu preserves case from metadata.yml.

    Author: Jove Moon will display Author: Jove Moon