Is it possible to add admonition support (!!! warning) to Zola? For example, Zola deletes the output directory when the server is killed. It might not be clear that the --output-dir flag will delete all data in the given directory, even if this directory already exists and contains data. I’d like to add a warning note for “–output-dir”. Maybe the command line should also warn if the directory given for --output-dir already exists.
I’ve made a quickstart section (currently called “Overview”) (https://github.com/photong/zola/blob/docs-next/docs/content/documentation/getting-started/overview.md) that shows how to make a very simple site. I’d like to add a more detailed “Tutorial” section that builds on this simple site to create a usable blog. I’m thinking of adding:
i. A basic theme (if Zola gets a default theme, use that; if not, use Bulma CSS framework).
ii. Posts with images (to show how asset colocation works).
iii. Blog sections made with folders (to show how _index.md works).
iv. Author information (as TOML file to show how data loading works).
v. An image gallery (to show the image processing features).
I think it would be better if output-dir refused to work if the outtput-dir is not empty.
There is already an image gallery in the image processing section.
Since themes have some limitations, it would be better to not have them in a tutorial unless it’s just using an existing theme. If you are making templates for your own site, there are no reasons to make it a theme.
I like the concept of building up on a concept (a blog here) a lot though! I think something like:
Basic theme => Sass usage
Going deeper with posts: syntax highlighting, asset colocation, pagination, taxonomies <== might be too much in one go
Another section (projects? trips?) rather than another blog thing
Building a search index? Not sure whether that’s worth having.
Checking your site with zola check
I’m not sure what you mean by author information with data loading?
Yes, refusing to work would be best (avoid possible data loss). I still hope that admonitions are added; they will be useful for many things (“tip”, “warning”, “note”, etc.).
I’ll link to the main image processing section when including the gallery in the example.
By “theme”, I mean just have the site look nice (basic css). Not an actual Zola theme. Like you mention, Sass usage.
syntax highlighting, asset colocation, pagination <- these sound good. I think taxonomies might be better for a “howto” article that focuses on just taxonomies. I’ll see how long the tutorial becomes.
Adding another section (projects, trips) is a great idea. Some SSGs don’t let you easily do that (Pelican) because they make assumptions about content.
Search might be better as a “howto” article.
I’ll include zola check.
“author information with data loading” <- Multi-author sites often have an author photograph, author biography, author social media links, etc. in an “Author” section at the end of an article. For my site, I store this information (for teachers) in a TOML file:
I then load this file on pages that need to display this information. If there’s a better way to do this, please let me know. Maybe this TOML data loading will be better as a howto.
Is it a good idea to put data into a config file? When I worked with Django, there were situations where it was useful to have two versions of a config file (e.g., “devel” and “production”).
It is useful to separate when you have multiple environments. It’s not really the case for a website. You might have slight tweaks such as baseUrl but not changing the site config/content.