DEV Community

Cover image for Create a minimal site with Elucid8
Richard Hainsworth
Richard Hainsworth

Posted on

Create a minimal site with Elucid8

#rakulang #webdev

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
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)