Create a minimal site with Elucid8

[Richard Hainsworth]

The Elucid8 system can be used to create websites based on RakuDoc. The article is to show how to create a minimal website.

Elucid8 ("elucidate") is still being developed, and more information can be found in the Github elucid8-org repositories.

The following need to be present:

1. A recent version of Rakudo v.2025.01 or later.
2. Dart sass - see Sass website for installation instructions.
3. Elucid8::Build - zef install Elucid8::Build
4. Elucid8::Run-locally - zef install Elucid8::Run-locally

Assuming that the zef installs bin/ files to a location in the PATH, then the utilities in the next section should run without problem.

Setting up minimal site​

In an empty directory (to be concrete, lets call it webdir), which will be the root for the website build, run the following

1. eluci8-setup
2. gather-sources
3. elucid8-build
4. run-locally

Then point a browser at localhost:5000

That is all for the minimum site.

Now change the file site-source/en/index.rakudoc.

Then run elucid8-build; run-locally again to see the changes.

Explanation of steps​

Step 1 Minimal files​

Here elucid8-setup copies resources in the Elucid8::Build distribution to create the minimal configuration entries in webdir,
a sample text and some minimal plugins.

The directory structure under webdir will be something like

- config/
  - 01-base.raku
  - 02-plugins.raku
  - 03-plugin-options.raku
  - 04-repos
- misc/
- site-sources/
  - en/
    - index.rakudoc
    - examples.rakudoc

Since Elucid8 is being built from the bottom up to be multi-lingual, it is intended that all of these directories can be named in a local variation. The file config/01-base.raku contains the tokens that are used within Elucid8::Build.

Step 2. Gathering sources​

It is intended that each set of language sources will be in a different repo. gather-sources looks at config/04-repos for files and repo information, clones repositories, runs git blame against them and stores a file description in misc/.

After this step, website will contain the file misc/repo-info.rakuon.

For the minimal website, the RakuDoc v2 specification is pulled from the Raku repository. This document also shows many of the features of RakuDoc.

The config/04-repos shows an example of how to map documents from the repository to subdirectories within publication.

Step 3 Build​

At this step, the build process starts. A processor engine is created that uses the plugins described in config/02-plugins. These are run with options described in config/03-plugin-options.

After this step, misc/ also contains ui-dictionary.rakuon, which will have the English version of the UI tokens. When this dictionary is appropriately edited, other languages will be available.

Elucid8 makes a distinction between the language of the UI and the language of the contents.

A new directory publication/ has now appeared, and this will contain the HTML version of the index file.

Step 4​

At this step, a Cro app is run that takes the HTML in publication and serves the files to localhost:5000.

Customisation​

There are many ways to customise the site:

• make sure to change config/03-plugin-options and the root-domain field of SiteMap, so that the SEO map points to your website.
• adding RakuDoc sources, remember to add links in index.rakudoc
• adding plugins to create new RakuDoc blocks
• use the ListFiles block to automatically include in index.rakudoc all the other RakuDoc sources in your local-sources/ directory.

Examples of what can be done can be seen in Sandpit repo, for Raku documentation

Continue reading...

 

Join 𝕋𝕄𝕋 on Telegram
Channel PREVIEW: