txt: ## dist_zef-finanalyst-Elucid8-Build.md
  # Build a website from current directory
  
  ```
  The Build component for the Elucid8 framework
  
  ```
  
  ---
  
  ## Table of Contents
  
  [SYNOPSIS](#SYNOPSIS)  
  [Assumptions](#Assumptions)  
  [Plugins](#Plugins)  
  [Render workflow](#Render_workflow)  
  [Configuration](#Configuration)  
    - [All configuration keys](#All_configuration_keys)  
  [Credits](#Credits)  
  [VERSION](#VERSION_0)
  
  ## SYNOPSIS
  
  The component is part of the `Elucid8` distribution and is installed as
  
  ```
      zef install Elucid8-build
  
  ```
  
  The utility `elucid8-build` will generate a static website according to the [configuration](Configuration) in the Current Working Directory (CWD).
  
  If the CWD is empty, `elucid8-build install` will create a default structure
  
  If the CWD has a custom (localised) config file, which may be any localised name, and the contents have the keys required (in English) but with localised values (eg. Kostom), then `elucid8-build --config=Kostom --install` then the subdirectories will be localised as well.
  
  Elucid8 may be used in two ways:
  
  1. All the RakuDoc sources are in the main website directory, under the `sources` subdirectory.
  2. The RakuDoc sources may be located in various repositories.
  
  For the second scenario, the `gather-sources` utility is used first. See [Gather and Build](Build-Gather.md) for more information.
  
  Once the website has been built, the `run-locally` utility will serve the HTML files, and can be browsed in a browser as `localhost:3000`. (The port can be changed in the plugins-configuration config).
  
  Run `elucid8-build -h` to get information on command line flags.
  
  Subsequent calls to `elucid8-build` will only rebuild modified source files, but see *-f* and *-with-only*
  
  ## Assumptions
  
  The Build component of Elucid8 assumes the following structure.
  
  ```
  sandpit                      # a test bed for a web site built with elucid8
      - config/                 # contains the website configuration
      - misc/                  # contains the dictionaries from the canonical to derived languages
      - sources/               # Only directories containing language sources permitted here
        - canonical/           # RakuDoc content in canonical language, which is en by default
        - xx/                  # content in language with code xx
        - xx-YY/               # regional content in language with code xx-YY
  
  ```
  
  All names in the structure, except for `config/`, may be modified by changing fields in the files in `config/`.
  
  The name of the ****config/**** directory may be changed by setting the `--config` option to `elucid8-build`. For example, if the canonical language is Mandarin, and the term used to mean 'config' is `布局`, then
  
  ```
  elucid8-build --config=<布局>
  
  ```
  
  will set the configuration directory *布局*. This will be called the *localised config*.
  
  ## Plugins
  
  The following HTML plugins are available:
  
  1. [UISwitcher](UISwitcher.md)
  2. SiteMap - creates `sitemap.xml` which can be read by robots
  3. AutoIndex - creates a `landing-page` file for the whole website from all glue files
  
  Each website can have its own plugins, stored in `local-lib`
  
  ## Render workflow
  
  For each human language (h-language), the sources files in the appropriately named sub-directory of `sources` (or local equivalent), each generate a separate web page.
  
  > Elucid8 is being designed for large websites and currently these are not optimally viewed using the *single page* paradigm. In the future, this view may change, in which case, each source will generate a section of the page.
  
  The source files in an h-language directory are of two sorts:
  
  1. content
  
  sources that are the basis of the website. They may contain explicit links to other pages.
  
  2. glue
  
  sources that are automatically generated to contain links to web pages generated by content (and possibly other glue) sources.
  
  3. info
  
  sources that contain site information not to be included in the search, such License or about.
  
  4. landing-page
  
  the name of the web page that is the default for a browser. By default it is auto-generated from the TITLEs and SUBTITLEs of the glue files in each h-language.
  
  Consequently,
  
  1. content web pages must be generated first
  2. info web pages must be generated next
  3. glue web pages must be generated after all content sources
  4. glue pages must be rendered in an explicit order
  5. if no content sources have changed since the last rendering, then glue web pages do not need to be re-generated, unless a glue source has itself been modified.
  
  In addition,
  
  1. a change in a canonical content source should trigger a change of style in the [equivalent content file](Canonical<->derived links)
  2. editing of derived sources will be more frequent than editing of the canonical sources
  
  For simplicity and initial development, the following are required:
  
  1. glue sources must be exist for each language (no super-language glue sources)
  2. the filename of each glue source must be the same in each directory
  3. content sources are implicitly assigned a generation order of zero
  4. the name and generation order of each glue source is defined in the config directory
  
  Consequently, the render order is as follows:
  
  1. the canonical language sources must be rendered first
  2. a content source is only re-generated if:
  
  2.1. the force flag is True
  
  2.2. there is no existing rendered file with the same name
  
  2.3. the content source is newer than the generate file
  
  1. if a canonical content source is re-generated, the equivalent source in all of the h-language directories must be re-generated too
  2. if a source (content or glue) is regenerated, all the glue files at the next generation order must be re-generated
  3. if no sources are regenerated at some level, then the glue sources at the next generation order do not need to be regenerated **unless** the glue source itself is modified. (This implies that changes cascade up the regeneration order)
  4. the sources in each derived language are rendered in an unspecified order of languages
  5. a content source is only re-generated if:
  
  7.1. the force flag is True
  
  7.2. the equivalent canonical source was rendered in this build cycle
  
  7.3. there is no existing rendered file with the same name
  
  7.4. the content source is newer than the generated file
  
  1. the glue sources are generated as per the canonical glue sources
  2. the **landing-page** is generated
  
  9.1. By default, a web page with the name **landing-page**\*.html\* is auto-generated
  
  9.2. If a source with the name **landing-page**\*.rakudoc\* exists in the ****sources**** directory, it is used to generate the landing page. A custom block is defined to add the glue contents that are auto-generated.
  
  ## Configuration
  
  A directory called `config/` (or its preconfigured alternative) is required in the CWD.
  
  The ****config/**** directory follows the conventions set out in the distribution `raku-config`.
  
  If a *localised config* has been specified, then one key must be called by the same name, and must contain a hash in which the key is a key of the default (English) *config* and the value is a string that is a key in the localised config.
  
  If some of the keys in the default are missing in the localised config, then the value of the default config is used.
  
  This allows for some or all of the configuration to be specified in a canonical language other than English.
  
  The full set of [configuration keys](All configuration keys) and their defaults are in English.
  
  For example, suppose we have a web-site where Welsh is the canonical language and the *config* file is partially in Welsh. Suppose further that the build command is:
  
  ```
      elucid8-build --config=ffurfwedd
  
  ```
  
  Then in this case, the directory `ffurfwedd/` should contain a file, typically named *01-ffurfwedd.raku*, with the content:
  
  ```
      ffurfwedd => %(
          sources => 'ffynhonnell',
          canonical => 'gofyddebol',
          Misc => 'lleoliad',
      )
  
  ```
  
  Then the web-site would need to be structured as follows
  
  ```
  <web-site directory>/
  |- config/
  |- lleoliad/
  |- ffurfwedd/
      |- 01-ffurfwedd.raku
  |- ffynhonnell/
      |- gofyddebol/
      |- en-GB/
  
  ```
  
  The **config** directory and its contents are needed because the localised config is incomplete.
  
  If **all** the mandatory config keys are defined in the *localised config*, and all the keys have values, then the default can be removed.
  
  ### All configuration keys
  
  The following is a list of all the mandatory config keys and their default values.
  
  | **Key name** | **Value** | **Description** |
  | --- | --- | --- |
  | misc | misc | the directory containing global information for translation, and file-data, repo-info |
  | sources | sources | content as RakuDoc sources, sub-directories are for content by language. See repositories |
  | canonical | canonical | sub-directory of sources containing content, only sub-dir that needs defining in the config file |
  | extensions | <rakudoc rakumod> | an array of file extensions containing source |
  | quiet | False | output runtime progress information |
  | with-only | () | a list of strings or regexes, matching filenames only will be rendered (useful for debugging) |
  | ignore | () | list of strings or regexes, matching files will not be rendered |
  | publication | 'publication' | directory relative to CWD where HTML and assets are rendered |
  | landing-page | 'index' | the name of the page that is the default route for a web-site |
  |  | The plugins needed are more easily kept in a separate file, typically `02-plugins.raku` |  |
  | plugins | <Bulma Hilite ListFiles> | plugins attached to the Rendering engine ***packaged with rakuast-rakudoc-render*** |
  | plugins | plugins ,= <Graphviz FontAwesome Latex LeafletMaps> | custom blocks ***packaged with rakuast-rakudoc-render*** |
  | plugins | plugins ,= 'UISwitcher', | Adds multi-lingual UI ***packaged with Elucid8*** |
  | plugins | plugins ,= 'SCSS', | must be last plugin enabled, converts SCSS in other plugins to CSS ***packaged with rakuast-rakudoc-render*** |
  
  ## Credits
  
  Richard Hainsworth, aka finanalyst
  
  ## VERSION
  
  v0.1.0
  
  ---
  
  ---
  
  Rendered from docs/README.rakudoc/README at 20:27 UTC on 2025-03-24
  
  Source last modified at 20:26 UTC on 2025-03-24
  