{"id":15061075,"url":"https://github.com/muhokama/ring","last_synced_at":"2025-04-10T06:36:52.568Z","repository":{"id":250332415,"uuid":"833921183","full_name":"muhokama/ring","owner":"muhokama","description":"A statically generated webring with YOCaml, because we love small-web","archived":false,"fork":false,"pushed_at":"2025-03-07T16:25:52.000Z","size":1243,"stargazers_count":20,"open_issues_count":0,"forks_count":10,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-07T02:36:56.854Z","etag":null,"topics":["ocaml","smallweb","syndication","webring"],"latest_commit_sha":null,"homepage":"https://ring.muhokama.fun","language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/muhokama.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-26T03:41:31.000Z","updated_at":"2025-03-07T16:19:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"fcb90102-92f2-4ccb-acc0-ec37732da145","html_url":"https://github.com/muhokama/ring","commit_stats":null,"previous_names":["muhokama/ring"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muhokama%2Fring","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muhokama%2Fring/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muhokama%2Fring/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muhokama%2Fring/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/muhokama","download_url":"https://codeload.github.com/muhokama/ring/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248170866,"owners_count":21059270,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ocaml","smallweb","syndication","webring"],"created_at":"2024-09-24T23:09:04.242Z","updated_at":"2025-04-10T06:36:52.514Z","avatar_url":"https://github.com/muhokama.png","language":"OCaml","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e [!WARNING]  \n\u003e This project uses a [developing version of\n\u003e YOCaml](https://gitlab.com/funkywork/yocaml) (to experiment with its\n\u003e expressiveness), so it is naturally also experimental and, above all, **work\n\u003e in progress** (and usable for the moment, but check back regularly to see how\n\u003e things are progressing :D).\n\n# ring.muhokama.fun\n\n\u003e **ring.muhokama.fun** is a [webring](https://en.wikipedia.org/wiki/Webring)\n\u003e built with [YOCaml](https://github.com/xhtmlboi/yocaml) which produces a\n\u003e static site. The medium-term aim is to create a small community, in homage to\n\u003e the [small-web](https://ar.al/2020/08/07/what-is-the-small-web/) of people\n\u003e with personal digital spaces (blog, wiki, site, galleries) who are used to\n\u003e exchanging information on common platforms. The project is largely (and\n\u003e freely) inspired by [webring de Merveilles](https://webring.xxiivv.com/)\n\n\u003c!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc --\u003e\n**Table of Contents**\n\n- [ring.muhokama.fun](#ringmuhokamafun)\n    - [Contribute to the content of the webring](#contribute-to-the-content-of-the-webring)\n        - [Join the chain](#join-the-chain)\n            - [Creating your identity](#creating-your-identity)\n            - [Adding the identity to the chain](#adding-the-identity-to-the-chain)\n            - [Linking the webring on your website](#linking-the-webring-on-your-website)\n        - [Area of interest](#area-of-interest)\n        - [Participation in the federated blog](#participation-in-the-federated-blog)\n    - [Contribute to the generator](#contribute-to-the-generator)\n        - [Setting up the development environment](#setting-up-the-development-environment)\n    - [Run the binary `ring.exe`](#run-the-binary-ringexe)\n    - [Launching tests](#launching-tests)\n    - [Project updates](#project-updates)\n    - [Generating documentation locally](#generating-documentation-locally)\n\n\u003c!-- markdown-toc end --\u003e\n\n\n## Contribute to the content of the webring\n\nIf you feel that you have something in common with the members of the ring, you\ncan of course add your personal space to the webring!\n\n### Join the chain\n\n#### Creating your identity\n\nThe process is fairly straightforward: just create a `your-ident.yml` file in\nthe [data/members/](data/members) directory. You can draw inspiration from the\nmembers already created, but the minimum data to be supplied are :\n\n```yaml\nid: your-ident\nmain_link:\n  url: your-website-url\n```\n\n\u003e [!WARNING]  \n\u003e Your id must have the same value as the file name (without the extension).\n\nHere's a slightly more expansive example that takes advantage of default\nsettings, inspired by my entry in the webring:\n\n```yaml\nid: xvw\ndisplay_name: Xavier Van de Woestyne\nbio: I'm a Belgian developer living in France (Nantes), very interested\n  in statically typed functional programming.\nlocation: France, Nantes\nmain_link:\n  url: https://xvw.lol\n  lang: fra\nmain_feed:\n  url: https://xvw.lol/atom.xml\n  lang: fra\nadditional_links:\n  - title: X\n    url: https://x.com/vdwxv\n  - title: Mastodon\n    url: https://merveilles.town/xvw\n  - title: Github\n    url: https://github.com\nadditional_feeds:\n  - title: Journal\n    url: https://xvw.lol/journal.xml\n```\n\nFor the moment, add-on information is used relatively little (the additional\nfeeds are used to generate the OPML file) but in the near future, it is likely\nthat this data will be used, for example, to build profile pages.\n\n#### Adding the identity to the chain\n\nNow that your identity has been created, you need to add it to the chain. To do\nthis, simply add your id to the [data/chain.yml](data/chain.yml) file, and\nyou're done! You can refers to [Setting up the development\nenvironment](#setting-up-the-development-environment) in order to test locally\nyour addition.\n\n#### Linking the webring on your website\n\nAs its aim is to create links between different sites, it's a good idea to add\nthe Webring to your personal site. It's fun to add the Webring to your personal\nsite. When you are added to the Webring (and it is activated). You will have two\ndedicated links:\n\n- `https://ring.muhokama.fun/u/\u003cYOUR-IDENT\u003e/pred` which redirects to the\n  previous member of the web ring\n- `https://ring.muhokama.fun/u/\u003cYOUR-IDENT\u003e/succ` which redirects to the next\n  member of the web ring\n  \nAn example that could be seen on your page would be: \n\n```html\nHey, this site is part of \n\u003ca href=\"https://ring.muhokama.fun\"\u003ering.muhokama.fun!\u003c/a\u003e\u003cbr /\u003e\n\u003ca href=\"https://ring.muhokama.fun/u/\u003cYOUR-IDENT\u003e/pred\"\u003ePrevious\u003c/a\u003e \n| \u003ca href=\"https://ring.muhokama.fun/u/\u003cYOUR-IDENT\u003e/succ\"\u003eNext\u003c/a\u003e\n```\n\nBut of course you're free to decide how you want it to look!\n\n### Area of interest\n\nThe webring index displays a (probably non-exhaustive) list of participants'\ninterests. If for some obscure reason you find that references are missing, you\ncan modify the `interests` section of the [data/index.md](data/index.md) page.\n\n### Participation in the federated blog\n\nThe [federated blog](https://ring.muhokama.fun/blog.html) allows you to share\narticles that are unified by the themes of the webring. Each reference to an\narticle lives in the [/data/articles](data/articles) directory and if you are\npart of the ring, you can add your articles freely. Imported items are\nreferenced in the [ring's Atom feed](https://ring.muhokama.fun/atom.xml).\n\n\n\n## Contribute to the generator\n\nThe Webring is a project that uses version 2 of\n[YOCaml](https://github.com/xhtmlboi/yocaml), a static site generator written in\n[OCaml](https://ocaml.org), which is very flexible and fun.\n\nThe project is divided into five parts:\n- `lib/` contains the library code used to describe the generator. This is where\n  all the webring's logic is to be found. (The library is called `Gem` (_because\n  I have a dubious sense of humour_)\n- `bin/` contains the binary code used to generate the site. It can be invoked\n  using the command `dune exec bin/ring.exe --help`. The binary simply invokes\n  the logical pipelines described in `lib`.\n- `data` contains the static data used to build the ring (participants,\n  participant chain, etc.). This is generally the part that is important for\n  adding or moderating participants in the ring.\n- `static` contains the static elements (images, css, templates) used to build\n  the HTML pages generated by the generator (for _front-end afficionados_).\n\n### Setting up the development environment\n\nTo work, we assume that a version greater than or equal to `2.2.0~beta1` of\n[OPAM](https://opam.ocaml.org) is installed on your machine ([Install\nOPAM](https://opam.ocaml.org/doc/Install.html), [upgrade to version\n`2.2.0~xxxx`](https://opam.ocaml.org/blog/opam-2-2-0-beta2/#Try-it)).\n\n\u003e [!TIP]  \n\u003e We're relying on version `2.2.x` to support the `dev-setup` flag, which allows\n\u003e development dependencies to be packaged, making it very practical to install\n\u003e locally all the elements needed to create a pleasant development environment.\n\nWhen you have a suitable version of OPAM, you can run the following command to\nbuild a [local switch](https://opam.ocaml.org/blog/opam-local-switches/) to\ncreate a sandboxed environment (with a good version of OCaml, and all the\ndependencies installed locally).\n\n```shell\nopam update\nopam switch create . --deps-only --with-dev-setup --with-test --with-doc -y\neval $(opam env)\n```\n\nAnd that's all there is to it. Launching `dune build` should build the project!\nAt present, the project simply prints to standard output, but you can build your\nproject in `bin/`. YOCaml and its various plugins will be accessible in the\nscope of this directory. The setup should work with Vim and Emacs (if they are\nconfigured to work with OCaml) and with any editor configured to use LSP (Merlin\nand OCaml-lsp-server being development dependencies of the project).\n\n\n## Run the binary `ring.exe`\n\nJust run the `ring.exe` binary compiled from `bin/ring.ml`, which should display\nthe `manpage`, giving information on how to interact with the binary, like this:\n\n```shell\ndune exec bin/ring.exe\n```\n\nBroadly speaking, here are the two main actions proposed by the `ring.exe`\nbinary:\n\n- `dune exec bin/ring.exe` display the manpage of the binary\n- `dune exec bin/ring.exe -- build [COMMON_OPTIONS]` builds the ring in `_www`\n  using the current directory as source\n- `dune exec bin/ring.exe -- watch [COMMON_OPTIONS] [--port PORT]` launches a\n  development server that rebuilds the ring each time a page is refreshed\n\nThe common options are:\n\n- `--target PATH` describes the compilation target (the directory where the ring\n  is to be built)\n- `--source PATH` describes the compilation source (the directory where the data\n  of the ring are located)\n- `--log-level (info | app | debug | error | warning)` describes the log-level\n\n## Launching tests\n\nThe build procedure is based on `dune`, without any particular sorcery, so\nissuing the following command is enough to run the tests:\n\n```shell\ndune test\n```\n\nFor more information on [dune](https://dune.build/) testing, please go to the\n[relevant manual page](https://dune.readthedocs.io/en/stable/tests.html).\n\n## Project updates\n\nWhen you have retrieved a new version of the project (from\n[github.com/muhokama/ring](https://github.com/muhokama/ring) for example), you\ncan run the following command to make sure that all the dependencies are\npresent:\n\n```shell\nopam update\nopam install . --deps-only --with-test --with-doc --with-dev-setup -y\n```\n\nThis is important because, for the moment, **ring** depends on a version of\nYOCaml that is currently under development.\n\n## Generating documentation locally\n\nYou can view the documentation for the entire project (and its dependencies)\nlocally by running the following command:\n\n```shell\ndune build @doc-new\n```\n\nThe doc will be generated in the following directory:\n`_build/default/_doc_new/html/docs/index.html` (with\n[Sherlodoc](https://doc.sherlocode.com/) for easy search by type).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuhokama%2Fring","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmuhokama%2Fring","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuhokama%2Fring/lists"}