This repository contains the source for Melange public documentation site.
If you are looking for Melange source instead, it can be found in https://github.com/melange-re/melange.
Warning At the moment, this is a work in progress, opened to the public. The content and technology used to build the website are being developed and the website itself is not hosted yet on its final domain.
After cloning the repository, install the necessary JavaScript packages:
yarn
Then run yarn docs:dev
from the folder where the repository lives.
Optionally, to run some of the tools to auto-generate parts of the documentation, you will need an opam switch with the required dependencies. To set it up, run:
make init
All code snippets should be written in OCaml syntax. A development-time script is available to automatically generate Reason syntax snippets from the OCaml ones. Before running this script, you will need to set up an opam switch. Instructions can be found in the "Tooling for docs generation" section.
To run the script:
dune build @re
To promote any changes to the original md
file, one can run:
dune build @re --auto-promote
Publishing is done automatically from GitHub actions:
- Every commit to
master
will publish in theunstable
folder - Every tag pushed with the
v*
format will publish on its corresponding folder
When a new version of melange
is published in opam, a new release of the docs
and playground should be published. The process is as follows:
- Update
documentation-site.opam
to pointmelange
andmelange-playground
packages to the commit of the new release (they need to be pinned so that the Melange docs can be accessed on a stable path) - Update versions of the compiler listed in the playground (
app.jsx
) - In the docs markdown pages, grep for the last version of Melange that was used and replace it with the newer one.
- Open a PR with the changes above
- After merging the PR, create a new branch
x.x.x-patches
. This branch will be used to publish any patches or improvements to that version of the docs / playground - In that branch, add a new command on the main
Makefile
to publish a new tag, e.g.
.PHONY: move-vx.x.x-tag
move-vx.x.x-tag: ## Moves the vx.x.x tag to the latest commit, useful to publish the vx docs
git push origin :refs/tags/vx.x.x
git tag -fa vx.x.x
git push origin --tags
- Call the newly created command to create a new version selectable from the
website:
make move-vx.x.x-tag
- Update the navigation bar in
docs/.vitepress/config.mts
, underthemeConfig.nav
setting, so that the first item is the one of the new version, andunstable
is shown last - Once the new version is published, we need to make sure other versions remain
SEO friendly:
- In
master
: updateadd_canonical
to point to the newvx.x.x
, so that theunstable
version of the docs starts referring to that version as the canonical one. To do so:- update the version in
add_canonical.ml
- run
dune test --auto-promote
- update the version in
- In
y.y.y-patches
: updateadd_canonical
in versiony.y.y
that was last before, to point tovx.x.x
as well. To do so:- update the version in
add_canonical.ml
- run
dune test --auto-promote
- uncomment the relevant code in
publish-version.yml
- update the version in
- In
- In the
gh-pages
branch:- replace the default version with the new one in index.html
- update
robots.txt
to point to the new version sitemap