Skip to content

Commit c83f5c5

Browse files
dannyadairdannyadair
committed
docs: clarify directories, document/page names, variant config
1 parent c834d30 commit c83f5c5

File tree

1 file changed

+21
-17
lines changed

1 file changed

+21
-17
lines changed

‎docs/configuration.md‎

Lines changed: 21 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,9 @@ At least `documents` has to be specified.
2929

3030
| Option | Type | Default | Description |
3131
| ------------------------------- | ------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
32-
| `documents` **required** | array | `[]` | List of document configurations. A simple string specifies the name of a directory containing a `config.yaml` file. You can also specify `path` and `name` to a specific configuration YAML file. |
33-
| `directories.base` **readonly** | string | directory containing the config file | Other directories are relative to this base directory. |
32+
| `documents` **required** | array | `[]` | List of document configurations. A simple string specifies the name of a directory under `directories.documents`. A directory needs to contain a `config.yaml` file. You can also specify `path` and `name` to a specific directory or configuration YAML file. |
33+
| `directories` | mapping | see the following settings | You can override default directories with the `directories` mapping, just re-define one or more with one of the following settings. |
34+
| `directories.base` **readonly** | string | directory containing the config file | If directories are not absolute paths they will be relative to this base directory. |
3435
| `directories.build` | string | `"build"` | Intermediary SVG and PDF files are written here. Deleted unless `bake` is run with `--keep-build` |
3536
| `directories.dist` | string | `"dist"` | Final PDF files are written here. |
3637
| `directories.documents` | string | `"."` | Location of document configurations. |
@@ -89,14 +90,16 @@ venue:
8990
9091
At least `filename` and `pages` has to be specified.
9192

92-
| Option | Type | Default | Description |
93-
| --------------------------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
94-
| _any main setting_ | | | Any of the Main Configuration File settings can be overridden for a particular document. |
95-
| `filename` **required** | string | | Filename (without extension) of the final PDF document. Can use variables, particularly `variant` (see [Variants](variants.md)) |
96-
| `pages` **required** | array | | List of page configurations. A simple string specifies a file by the same name with `.yaml` extension in the document's _pages_ directory. You can also specify a `path` and `name` to a specific file (absolute or relative to the document's base directory). |
97-
| `variants` | array | | List of document variants (see [Variants](variants.md)). These are their own sections which will be merged with the document configuration. During processing, `variant` will hold the current variant configuration. |
98-
| `custom_bake` | string | `"bake.py"` | Python file used for custom processing (if found). A simple string specifies a filename in the document's _base_ directory. You can also specify a `path` and `name` to a specific file (absolute or relative to the document's _base_ directory). |
99-
| _additional custom setting_ | | | Any settings you want to make available to all pages of this document. |
93+
| Option | Type | Default | Description |
94+
| --------------------------- | ------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
95+
| _any main setting_ | | | Any of the Main Configuration File settings can be overridden for a particular document. `directories.base` is now the directory containing the document configuration file. |
96+
| `name` | string | as per main config `documents` | Name of the document. If a simple string or `name` was specified then that will be name. If a directory was specified it will be the name of the directory. If a config file was specified it will be the file name without extension. |
97+
| `filename` **required** | string | | Filename (without extension) of the final PDF document. Can use variables, particularly `variant` (see [Variants](variants.md)) |
98+
| `pages` **required** | array | | List of page configurations. A simple string specifies a file by the same name with `.yaml` extension in the document's _pages_ directory. You can also specify a `path` and `name` to a specific file (absolute or relative to the document's base directory). |
99+
| `variants` | array | | List of document variants (see [Variants](variants.md)). These are their own sections which will be merged with the document configuration. During processing, `variant` will hold the current variant configuration. |
100+
| `variant` **readonly** | mapping | | The configuration of the currently processed variant. This is merged into the document configuration but also available on its own so you can refer to `variant.name` etc. |
101+
| `custom_bake` | string | `"bake.py"` | Python file used for custom processing (if found). A simple string specifies a filename in the document's _base_ directory. You can also specify a `path` and `name` to a specific file (absolute or relative to the document's _base_ directory). |
102+
| _additional custom setting_ | | | Any settings you want to make available to all pages of this document. |
100103

101104
<details>
102105
<summary>Example Document Configuration File</summary>
@@ -120,13 +123,14 @@ pages:
120123

121124
At least `template` has to be specified.
122125

123-
| Option | Type | Default | Description |
124-
| ------------------------------ | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
125-
| _any main or document setting_ | | | Any of the Main/Document Configuration File settings can be overridden for a particular page. |
126-
| `template` **required** | string | | Filename of the SVG template (must be in the document's `templates/` directory) |
127-
| `images` | array | | List of images to use in the page. Each image must have a `name` (filename in the document's `images/` directory) and optionally a `type` (defaults to "default") |
128-
| `page_number` **readonly** | integer | | The number of the current page within its document |
129-
| _additional custom setting_ | | | Any settings you want to make available to this page. This allows you to have a template purely for layout purposes. |
126+
| Option | Type | Default | Description |
127+
| ------------------------------ | ------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
128+
| _any main or document setting_ | | | Any of the Main/Document Configuration File settings can be overridden for a particular page. `directories.base` is now the directory containing the page configuration file. |
129+
| `name` | string | as per document config `pages` | Name of the page. If a simple string or `name` was specified then that will be name. If a directory was specified it will be the name of the directory. If a config file was specified it will be the file name without extension. |
130+
| `template` **required** | string | | Filename of the SVG template (must be in the document's `templates/` directory) |
131+
| `images` | array | | List of images to use in the page. Each image must have a `name` (filename in the document's `images/` directory) and optionally a `type` (defaults to "default") |
132+
| `page_number` **readonly** | integer | | The number of the current page within its document |
133+
| _additional custom setting_ | | | Any settings you want to make available to this page. This allows you to have a template purely for layout purposes. |
130134

131135
<details>
132136
<summary>Example Page Configuration File</summary>

0 commit comments

Comments
 (0)