Repository files navigation

ring.muhokama.fun is awebringbuilt withYOCaml which produces astatic site. The medium-term aim is to create a small community, in homage tothesmall-web of peoplewith personal digital spaces (blog, wiki, site, galleries) who are used toexchanging information on common platforms. The project is largely (andfreely) inspired bywebring de Merveilles

Table of Contents

• ring.muhokama.fun
  • Contribute to the content of the webring
    • Join the chain
      • Creating your identity
      • Adding the identity to the chain
      • Linking the webring on your website
    • Area of interest
    • Participation in the federated blog
  • Contribute to the generator
    • Setting up the development environment
  • Run the binaryring.exe
  • Launching tests
  • Project updates
  • Generating documentation locally

If you feel that you have something in common with the members of the ring, youcan of course add your personal space to the webring!

The process is fairly straightforward: just create ayour-ident.yml file inthedata/members/ directory. You can draw inspiration from themembers already created, but the minimum data to be supplied are :

id:your-identmain_link:url:your-website-url

Here's a slightly more expansive example that takes advantage of defaultsettings, inspired by my entry in the webring:

id:xvwdisplay_name:Xavier Van de Woestynebio:I'm a Belgian developer living in France (Nantes), very interestedin statically typed functional programming.location:France, Nantesmain_link:url:https://xvw.lollang:framain_feed:url:https://xvw.lol/atom.xmllang:fraadditional_links:  -title:Xurl:https://x.com/vdwxv  -title:Mastodonurl:https://merveilles.town/xvw  -title:Githuburl:https://github.comadditional_feeds:  -title:Journalurl:https://xvw.lol/journal.xml

For the moment, add-on information is used relatively little (the additionalfeeds are used to generate the OPML file) but in the near future, it is likelythat this data will be used, for example, to build profile pages.

Now that your identity has been created, you need to add it to the chain. To dothis, simply add your id to thedata/chain.yml file, andyou're done! You can refers toSetting up the developmentenvironment in order to test locallyyour addition.

As its aim is to create links between different sites, it's a good idea to addthe Webring to your personal site. It's fun to add the Webring to your personalsite. When you are added to the Webring (and it is activated). You will have twodedicated links:

• https://ring.muhokama.fun/u/<YOUR-IDENT>/pred which redirects to theprevious member of the web ring
• https://ring.muhokama.fun/u/<YOUR-IDENT>/succ which redirects to the nextmember of the web ring

An example that could be seen on your page would be:

Hey, this site is part of<ahref="https://ring.muhokama.fun">ring.muhokama.fun!</a><br/><ahref="https://ring.muhokama.fun/u/<YOUR-IDENT>/pred">Previous</a> |<ahref="https://ring.muhokama.fun/u/<YOUR-IDENT>/succ">Next</a>

But of course you're free to decide how you want it to look!

The webring index displays a (probably non-exhaustive) list of participants'interests. If for some obscure reason you find that references are missing, youcan modify theinterests section of thedata/index.md page.

Thefederated blog allows you to sharearticles that are unified by the themes of the webring. Each reference to anarticle lives in the/data/articles directory and if you arepart of the ring, you can add your articles freely. Imported items arereferenced in thering's Atom feed.

The Webring is a project that uses version 2 ofYOCaml, a static site generator written inOCaml, which is very flexible and fun.

The project is divided into five parts:

• lib/ contains the library code used to describe the generator. This is whereall the webring's logic is to be found. (The library is calledGem (becauseI have a dubious sense of humour)
• bin/ contains the binary code used to generate the site. It can be invokedusing the commanddune exec bin/ring.exe --help. The binary simply invokesthe logical pipelines described inlib.
• data contains the static data used to build the ring (participants,participant chain, etc.). This is generally the part that is important foradding or moderating participants in the ring.
• static contains the static elements (images, css, templates) used to buildthe HTML pages generated by the generator (forfront-end afficionados).

To work, we assume that a version greater than or equal to2.2.0~beta1 ofOPAM is installed on your machine (InstallOPAM,upgrade to version2.2.0~xxxx).

When you have a suitable version of OPAM, you can run the following command tobuild alocal switch tocreate a sandboxed environment (with a good version of OCaml, and all thedependencies installed locally).

opam updateopam switch create. --deps-only --with-dev-setup --with-test --with-doc -yeval$(opam env)

And that's all there is to it. Launchingdune build should build the project!At present, the project simply prints to standard output, but you can build yourproject inbin/. YOCaml and its various plugins will be accessible in thescope of this directory. The setup should work with Vim and Emacs (if they areconfigured to work with OCaml) and with any editor configured to use LSP (Merlinand OCaml-lsp-server being development dependencies of the project).

Just run thering.exe binary compiled frombin/ring.ml, which should displaythemanpage, giving information on how to interact with the binary, like this:

duneexec bin/ring.exe

Broadly speaking, here are the two main actions proposed by thering.exebinary:

• dune exec bin/ring.exe display the manpage of the binary
• dune exec bin/ring.exe -- build [COMMON_OPTIONS] builds the ring in_wwwusing the current directory as source
• dune exec bin/ring.exe -- watch [COMMON_OPTIONS] [--port PORT] launches adevelopment server that rebuilds the ring each time a page is refreshed

The common options are:

• --target PATH describes the compilation target (the directory where the ringis to be built)
• --source PATH describes the compilation source (the directory where the dataof the ring are located)
• --log-level (info | app | debug | error | warning) describes the log-level

The build procedure is based ondune, without any particular sorcery, soissuing the following command is enough to run the tests:

dunetest

For more information ondune testing, please go to therelevant manual page.

When you have retrieved a new version of the project (fromgithub.com/muhokama/ring for example), youcan run the following command to make sure that all the dependencies arepresent:

opam updateopam install. --deps-only --with-test --with-doc --with-dev-setup -y

This is important because, for the moment,ring depends on a version ofYOCaml that is currently under development.

You can view the documentation for the entire project (and its dependencies)locally by running the following command:

dune build @doc-new

The doc will be generated in the following directory:_build/default/_doc_new/html/docs/index.html (withSherlodoc for easy search by type).