Use conventional directory names #35

New Issue

ktyl · 2024-06-16T17:34:42+02:00

ktyl commented

2024-06-16 17:34:42 +02:00

We use a number of specifically named directories when building the site:

root: contains base HTML pages, which have elements injected into them before they copied to the output
inc_html: contains snippets of HTML which are injected into the base pages
site: output directory.

kiln and zola follow a common convention which partially matches ours:

content: general site content
static: pages which are copied unmodified into the output
templates: snippets used to construct full pages
public: output directory

Right away, we could rename site->public as they match entirely. However, the content,static and templates folders have no direct analogue.

content is desirable: pages in content should form the majority of site pages. These would have a common layout, and be generated from Markdown source as the current blog pages are.

The only current page which would fit into the static directory is the vn, but this may no longer be true when trying to apply a style to it (#25). We would like to have a content system similar to the current blog page generation, where Markdown source is converted to HTML pages, and we would also like to support writing HTML verbatim for more complex pages.

templates in other SSGs imply the use of a templating engine: at present our templating needs are actually quite basic, and should be be possible to meet with ad-hoc Python scripting. This may prove to be inadequate in the long-term, but in the short-term avoids adding a dependency. Therefore, a templates directly holds some utility - it allows us to write chunks of HTML for use by Python scripts when filling out pages. They will be templates, but in a very primitive sense.

We use a number of specifically named directories when building the site: * `root`: contains base HTML pages, which have elements injected into them before they copied to the output * `inc_html`: contains snippets of HTML which are injected into the base pages * `site`: output directory. [kiln](https://kiln.adnano.co/02-setup/) and [zola](https://www.getzola.org/documentation/getting-started/overview/) follow a common convention which partially matches ours: * `content`: general site content * `static`: pages which are copied unmodified into the output * `templates`: snippets used to construct full pages * `public`: output directory Right away, we could rename `site`->`public` as they match entirely. However, the `content`,`static` and `templates` folders have no direct analogue. `content` is desirable: pages in `content` should form the majority of site pages. These would have a common layout, and be generated from Markdown source as the current blog pages are. The only current page which would fit into the `static` directory is the vn, but this may no longer be true when trying to apply a style to it (#25). We would like to have a content system similar to the current blog page generation, where Markdown source is converted to HTML pages, and we would also like to support writing HTML verbatim for more complex pages. `templates` in other SSGs imply the use of a templating engine: at present our templating needs are actually quite basic, and should be be possible to meet with ad-hoc Python scripting. This may prove to be inadequate in the long-term, but in the short-term avoids adding a dependency. Therefore, a `templates` directly holds some utility - it allows us to write chunks of HTML for use by Python scripts when filling out pages. They will be templates, but in a very primitive sense.

ktyl added the

enhancement

label 2024-06-16 17:34:42 +02:00

Sign in to join this conversation.