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 (1)

Collapse
 
wayland profile image
Tim Nelson • • Edited

Hi!

Thanks for the post; it's enough to get me started I think :) . Some feedback:

  • You incorrectly spelled elucid8-setup (correct) as eluci8-setup (incorrect)
  • Mine came up on port 3000, not 5000. Not sure if that's something at my end or yours.
  • What should I include in my .gitignore ? Everything created from step 2 onwards?
  • What steps do I need to do to build the site each time I change something?
  • Do I need to keep the imported rakudoc repo (is it just an example?), or should I replace it with the content of my site?
  • What do I need to do to run the site on the public internet? By which I specifically mean, is there a substitute for the run-locally command, or should I be running that in a container on the Internet?
  • When I ran elucid8-build, I got the error RakuDoc::Plugin::SCSS Plugin fails because the program sass is not reachable. Possibly this is because I installed sass locally in my project, rather than globally, but a hint of direction about how to install sass wouldn't go astray.
  • The minimal site is just about unusable in Firefox (overlapping text, etc). I realise it's a work in progress. Let me know if I should submit a bug report for that somewhere.
  • I added some new content (files under site-source, eg. site-sources/en/tools/index.rakudoc), and did another elucid8-build, but no new files appeared in publication/en. I've tried running raku --doc=HTML site-sources/en/tools/index.rakudoc (which worked) and raku --rakudoc=HTML site-sources/en/tools/index.rakudoc (which had no output, not even an error).

Having said all that, thanks again for the article, and for the software :) .

Thanks!