Build a website from current directory#

The Build component for the Elucid8 framework

Table of Contents#

SYNOPSIS
Assumptions
Plugins
Render workflow
Configuration
  - All configuration keys
Credits
VERSION

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 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 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

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.

Credits#

Richard Hainsworth, aka finanalyst

VERSION#

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