Muwu User Guide

Project Options

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

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.

Some options allow multiple values in the form of a comma-separated list.

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

generate_topic_inner_identifiers

possible values

false

true

default value

false

false

Muwu will convert markdown to html without adding identifying attributes.

true

Muwu will add the following attributes to the output html:

data-topic-source-class may contain several values identifying the path to the source file and the type of html element
data-topic-id-class contains a unique number for the source file and the type of html element

These attributes can be used to uniquely style individual components of the outline.

6.4

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.5

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.6

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.7

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.8

markdown_renderer

6.9

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.10

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.11

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.12

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.13

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.14

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.15

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.16

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.17

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.18

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.19

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.20

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.21

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.22

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.23

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.