8

Troubleshooting a Project

Note: This section is still in development in response to real-use cases.

8.1 Projects that Compile

8.1.1

If Content Is Missing

Use the muwu inspect command to see where Muwu will look for source text files.

Are your source text files where Muwu expects?
- Muwu looks for source text files in the text/ folder, not the project home directory.
- Using multiple text section names will imply their own subfolder from text/.
Are you intending to include a Haml file?
- Look for a Markdown file with the same basname.
- Muwu will prefer Mardown files over Haml files.
Review the sections of this guide:
- Outlining a Project -> Headings and Filenames
- Project Options -> outline_text_pathnames

8.1.2

If Formatting Is Incorrect

Use the muwu inspect command to see whether the style sheet compiles to an external file or to the <head> section of the html file.

Try reloading the page.
- The web browser might be using a cached version.
Check the terminal window for a report from the compiler.
- If there are Sass exceptions, the style sheet might not have compiled; see the following section, Sass Exceptions, for troubleshooting.
Be sure that the affected layout is included in the CSS manifest file.
Be sure that the CSS is adequately specified.
- The style sheet heirarchy for Muwu is still in development. Markdown does not give any class or id attributes to the HTML elements it creates, so Muwu adds attributes to its container elements.
- Generally speaking, web browsers will prioritize CSS from selectors that are more specific over ones that are less specific; and selectors that appear later in the manifest over ones that appear earlier.
Try recompiling the project.

8.2 Projects that Do Not Compile

8.2.1

Muwu Exceptions

Most project exceptions are warnings that will not prevent Muwu from compiling a project to whatever extent it is able. However, some exceptions will stop a project from compiling.

“Is this a Muwu project folder?”

Muwu could not find files with which to build a project.

Be sure you are running the muwu command from the project home directory, not from a subfolder.
Be sure the following files exist in the project home directory:
- metadata.yml
- options.yml
- outline.yml

“The output destination ‘stdout’ can only accommodate a single outlined document.”

The values for output_destination and output_formats conflict with each other.

Change the value for output_destination to file, or, remove the document separators from the outline so the project compiles to only one document.

“The option destination ‘stdout’ can only accommodate a single output format.”

The values for output_destination and output_formats conflict with each other.

Change the value for output_destination to file, or, remove values css or js from output_formats.

8.2.2

Yaml Exceptions

Muwu uses only a subset of Yaml for the metadata, outline, and options. At the time of this writing, the Psych gem handles and reports Yaml errors.

Guidelines for Yaml files:

Metadata should be key-value pairs.
```
author: Jove Moon
```
The outline should be a list, with each line beginning with a hyphen. Nested text sections should be indented two spaces, and the parent heading should end with a colon.
```
- Tuesday:
  - Gray skies
  - A gust of wind
```
Options should be key-value pairs. If an option allows multiple values, separate the values with a comma.
```
output_formats: css, html, js
render_punctuation_smart: true
```

8.2.3

Sass exceptions

At the time of this writing, the SassC gem handles and reports errors in style sheets.

Muwu User Guide

8