638e83e9dc
This removes mdBook in favor of a flat docs folder generating a single `README.md` in the repository root. Installation and usage instructions have also been expanded slightly.
1.9 KiB
Advanced usage
Frontmatter
By default, frontmatter is copied over "as-is".
Some static site generators are picky about frontmatter and require it to be present.
Some get tripped up when Markdown files don't have frontmatter but start with a list item or horizontal rule.
In these cases, --frontmatter=always can be used to insert an empty frontmatter entry.
To completely remove any frontmatter from exported notes, use --frontmatter=never.
Ignoring files
By default, hidden files, patterns listed in .export-ignore as well as any files ignored by git (if your vault is part of a git repository) will be excluded from exports.
These options may be adjusted with --hidden, --ignore-file and --no-git if desired.
(See --help for more information).
Notes linking to ignored notes will be unlinked (they'll only include the link text). Embeds of ignored notes will be skipped entirely.
Ignorefile syntax
The syntax for .export-ignore files is identical to that of gitignore files.
Here's an example:
# Ignore the directory private that is located at the top of the export tree
/private
# Ignore any file or directory called `test`
test
# Ignore any PDF file
*.pdf
# ..but include special.pdf
!special.pdf
For more comprehensive documentation and examples, see the gitignore manpage.
Recursive embeds
It's possible to end up with "recursive embeds" when two notes embed each other.
This happens for example when a Note A.md contains ![[Note B]] but Note B.md also contains ![[Note A]].
By default, this will trigger an error and display the chain of notes which caused the recursion.
This behavior may be changed by specifying --no-recursive-embeds.
Using this mode, if a note is encountered for a second time while processing the original note, instead of embedding it again a link to the note is inserted instead to break the cycle.