Muwu User Guide

6 Project Options
6.1 generate_navigators_automatically
6.2 generate_subcontents_automatically
6.3 html_head_includes_metadata_tags
6.4 html_lang
6.5 html_uses_javascript_navigation
6.6 markdown_allows_raw_html
6.7 markdown_renderer
6.8 outline_text_pathnames
6.9 output_destination
6.10 output_file_css_basename
6.11 output_file_html_basename
6.12 output_file_js_basename
6.13 output_formats
6.14 remote_publish
6.15 remote_sync
6.16 render_punctuation_smart
6.17 render_section_end_links
6.18 render_section_numbers
6.19 render_sections_distinctly_depth_max
6.20 render_title_section_metadata
6.21 rsync_options
6.22 warning_if_parent_heading_lacks_source

6

Project Options

The file options.yml contains settings that affect the output of the compiled project. If a setting is not present in options.yml, Muwu will use the default value.

6.1

generate_navigators_automatically

possible values

false

true

default value

true

false

The outline must specify navigator sections.

true

If the outline has more than one document, Muwu will automatically put a navigator section at the top and bottom of each document.

6.2

generate_subcontents_automatically

possible values

false

true

default value

false

false

The outline must specify any subcontents sections.

true

If the outline has more than one document, Muwu will automatically put a subcontents section in each document, before the compiled text.

6.3

html_head_includes_metadata_tags

possible values

false

true

default value

true

false

Muwu will only include <meta> tags for document operability (such as proper display for mobile devices) in the header of each html document.

true

Muwu will put <meta> tags in the header of each html document, containing the project metadata from metadata.yml. (These will not be displayed in the compiled text.) Muwu will also include <meta> tags for document operability.

6.4

html_lang

possible values

[language code]

[nil]

default value

[nil]

[language code]

If the value matches one of the ISO-639-1 language codes, Muwu will include the lang= attribute in the <HTML> tag.

[nil]

For an nil value, Muwu will not include the lang= attribute in the <HTML> tag.

6.5

html_uses_javascript_navigation

possible values

false

true

default value

false

false

Navigating via the links in the compiled project will add to the history of the web browser. The back and forward buttons of the web browser would follow of the links. This is standard HTTP behavior.

true

Navigating via the links in the compiled project will use javascript, and will not add to the history of the web browser. The back and forward buttons would leave the project page.

If a web browser does not have javascript, a web browser will still be able to navigate between pages using standard HTTP behavior.

6.6

markdown_allows_raw_html

possible values

false

true

default value

true

false

Muwu will exclude raw HTML from markdown files by escaping characters <, >, and & before sending the source text to the markdown engine. Note that this will cause incompatibility with inline and fenced code blocks, because any escaped HTML sequences would be shown instead of the characters they represent.

true

Muwu will allow raw HTML within markdown files, according to the specifications of the markdown engine.

6.7

markdown_renderer

possible values

commonmarker

motion-markdown-it

default value

commonmarker

commonmarker

Compiles quickly.

motion-markdown-it

Contains support for Pandoc-style description lists, but compiles more slowly. Commonmark-compliant.

6.8

outline_text_pathnames

possible values

explicit

flexible

implicit

default value

implicit

explicit

Each entry in the outline is a literal path to a file in the text/ folder.

flexible

Outline entries that end in .md are explicit. Those that do not are implicit.

implicit

Muwu will derive a filename from each entry in the outline and its parent headings.

6.9

output_destination

possible values

file

stdout

default value

file

file

Muwu will compile to files in the project directory.

stdout

Muwu will compile to the standard output device (usually your monitor).

Requires output_formats: html (without css or js)

6.10

output_file_css_basename

possible values

[filename]

[nil]

default value

[nil]

[filename]

Muwu will use any name entered as the basename for the stylesheet file. The filename must only contain word characters [a-zA-Z0-9_]. Muwu will replace non-word characters with an underscore.Muwu will add the .css file extension.

[nil]

Muwu will use the metadata value for slug as the name for the stylesheet file. If slug is not defined, Muwu will use the name of the project directory. Muwu will add the .css file extension.

6.11

output_file_html_basename

possible values

[filename]

[nil]

default value

[nil]

[filename]

Muwu will use any name entered as the basename for the html file. The filename must only contain word characters [a-zA-Z0-9_]. Muwu will replace non-word characters with an underscore. Muwu will add the .html file extension.

[nil]

Muwu will use the metadata value for slug as the name for the html file. If slug is not defined, Muwu will use the name of the project directory. Muwu will add the .html file extension.

6.12

output_file_js_basename

possible values

[filename]

[nil]

default value

[nil]

[filename]

Muwu will use any name entered as the basename for the javascript file (if applicable). The filename must only contain word characters [a-zA-Z0-9_]. Muwu will replace non-word characters with an underscore. Muwu will add a .js file extension.

[nil]

Muwu will use the metadata value for slug as the name for the javascript file. If slug is not defined, Muwu will use the name of the project directory. Muwu will add the .js file extension.

6.13

output_formats

possible values

css

html

js

default value

css, html, js

css

Compile the stylesheet into a separate file.

Requires the html value.

Requires output_formats: file.

html

Compile the project into html. If css or js do not accompany html, the final html document(s) will include the stylesheet and (if applicable) the javascript libraries, respectively, in the <head> element.

js

Compile the javascript libraries (if applicable) stylesheet into a separate file.

Requires the html value.

Requires output_formats: file.

Multiple values are possible.

6.14

remote_publish

possible values

[user@ip:path]

default values

[none]

The project action muwu publish will attempt to open a connection via rsync to this URL.

6.15

remote_sync

possible values

[user@ip:path]

default values

[none]

The project action muwu sync will attempt to open a connection via rsync to this URL.

6.16

render_punctuation_smart

possible values

false

true

default value

true

false

Punctuation will be preserved as typed in the source text.

true

The Markdown renderer will substitute typographic punctuation, for example, curly quotes for straight quotes.

6.17

render_section_end_links

possible values

contents

home

top

default value

contents, top

contents

Muwu will make a navigation link at the end of the section to the section’s heading in the table of contents.

home

Muwu will make a navigation link to the top of the first document.

top

Muwu will make a navigation link to the top of the current document.

Multiple values are possible.

6.18

render_section_numbers

possible values

false

true

default value

true

false

Muwu will not display section numbers in the compiled project. Muwu will still include section numbers as attributes in the inspector and the compiled project for troubleshooting and identification purposes.

true

Muwu will display section numbers in the compiled project.

6.19

render_sections_distinctly_depth_max

possible values

[integer]

[nil]

default value

[nil]

[integer]

Muwu will distinctly identify text sections up to, and including, the given depth level. Muwu will give included text sections an entry in the table of contents. Muwu will also display a section number for included sections.

[nil]

Muwu will distinctly identify all text sections. Muwu will give all text sections an entry in the table of contents. Muwu will display a section number for all sections.

6.20

render_title_section_metadata

possible values

[any metadata keys]

default value

title, subtitle, author

[any metadata keys]

Muwu will include the values for any given metadata keys, in the order provided, when making a title section. This option is an alternative to specifying metadata keys in the title keyword of the outline. If the title section in the outline indicates specific metadata keys, the outline will override this option.

Multiple values are possible.

6.21

rsync_options

possible_values

[any of the rsync command line options]

default_values

--itemize-changes --recursive --verbose

The project actions muwu publish and muwu sync will automatically run rsync with the given values, exactly as entered. See the rsync man page for detailed information.

6.22

warning_if_parent_heading_lacks_source

possible values

false

true

default value

true

false

Muwu will not issue a warning if a parent heading in the outline does not have a corresponding source text file.

true

Muwu will issue a warning if a parent heading in the outline does not have a corresponding source text file.