22. Configuration file
So I had a problem where the text on the index page was missing. After a certain amount of second-guessing myself I worked out how it was supposed to work, and what I had got wrong. So now I want to prevent myself from repeating the mistake.
What went wrong
There are two sources of pages in the Mismiy site: pages and posts.
When rendering pages, the entries in posts are treated specially:
they need to have publication dates, and they are included in the
reverse-chronological list of posts.
The index page—the one with that list—will take its text from a
page named index. In other words, from a Markdown file named
index.md or index.markdown. This can’t be a post because
of the special nature of posts, so it lives in the pages directory.
The mismiy command has arguments telling it which directories
to look in. The default is just posts. So if I run it as
mismiy -w
as I generally do, then it does not process pages in the pages
directory. Hence no intro on the index page. Duh.
So I need to remember this when I run the command.
How Mismiy can help
The specific problem here is that Mismiy did not guess that pages
was an additional source directory. Two options to address this
would be
- Have a list of well-known source names (
posts,pages,about, …) and make the default be all of those directories that exist; or, more dangerously, - Search for all directories in the current directory that have at least one Markdown file in them.
I think the second of these is a bit too likely to discover a forbidden drafts directory by mistake, so I think the former is a better bet.
The more general issue is I need to remember a set of command-line
options to the mismiy command. Two options to address this:
- Write a README file with the command in it to copy & paste, and resolve to not forget to read the README when returning to the project after a while; or
- Some kind of configuration file that records the default options.
Let‘s consider option 4. The options that make sense for a configuration file are these:
| Option | Type | CLI equiv | Default |
|---|---|---|---|
locale |
like en_GB.utf-8 |
--locale |
– |
omit_dot_html |
boolean | --omit-dot-html |
false |
out_dir |
--out-dir |
pub |
|
static_dir |
directory | --static-dir |
static |
templates_dir |
directory | --templates-dir |
templates |
pages_dirs |
list of directories | posts |
My feeling is that --watch, --drafts and --as-of do not make
sense as default arguments.
Now, when Mismiy starts up, it looks for a file mismiy-config.yaml,
and, if it exists, parses it for defaults for these options. If the
options are also specified on the command line, that takes
precedence. If neither specifies a value then the default from the
table is used.
As a result, once this is set up, it should be possible to carelessly
mismiy -w and have it do what you expect.
Posts on similar topics