In order to avoid long, confusing URLs on the OCaml Manual pages, we set out to create a solution that shortens these URLs, including section references, and contains the specific version. The result improves readability and user experience. This article outlines the motivation behind these changes and how we implemented them.

Challenge

The OCaml HTML manuals have URL references such as https://v2.ocaml.org/manual/types.html#sss:typexpr-sharp-types, and they do not refer to any specific compiler version. We needed a way to easily share a link with the version number included. The OCaml.org page already has a mention of the compiler version, but it refers to specific https://ocaml.org/releases.

We wanted a canonical naming convention that is consistent with current and future manual releases. It would also be beneficial to have only one place to store all the manuals, and the users of OCaml.org should never see redirecting URLs in the browser. This will greatly help increase the overall backlink quality when people share the links in conversations, tutorials, blogs, and on the Web. A preferred naming scheme should be something like:

https://v2.ocaml.org/releases/latest/manual/attributes.html https://v2.ocaml.org/releases/4.12/manual/attributes.html

Using this, we redirected the v2.ocaml.org to OCaml.org for the production deployment. Also, the changes help in shorter URLs that can be easily remembered and shared. The rel="canonical" is a perfectly good way to make sure only https://ocaml.org/manual/latest gets indexed.

Implementation

After a detailed discussion, the following UI mockup to switch manuals was provided via GitHub issue, and Option A was selected.

Our proposed changes to the URL are shown below:

Current: https://v2.ocaml.org/releases/5.1/htmlman/index.html
Suggested: https://ocaml.org/manual/5.3.0/index.html

Current: https://v2.ocaml.org/releases/5.1/api/Atomic.html
Suggested: https://ocaml.org/manual/5.3.0/api/Atomic.html

HTML Compiler Manuals

The HTML manual files are hosted in a separate GitHub repository at https://github.com/ocaml-web/html-compiler-manuals/. It contains a folder for each compiler version, and it also has the manual HTML files.

A script to automate the process of generating the HTML manuals is also available at https://github.com/ocaml-web/html-compiler-manuals/blob/main/scripts/build-compiler-html-manuals.sh. The script defines two variables, DIR and OCAML_VERSION, where you can specify the location to build the manual and the compiler version to use. It then clones the ocaml/ocaml repository, switches to the specific compiler branch, builds the compiler, and then generates the manuals. The actual commands are listed below for reference:

echo "Clone ocaml repository ..."
git clone git@github.com:ocaml/ocaml.git

# Switch to ocaml branch
echo "Checkout $OCAML_VERSION branch in ocaml ..."
cd ocaml
git checkout $OCAML_VERSION

# Remove any stale files
echo "Running make clean"
make clean
git clean -f -x

# Configure and build
echo "Running configure and make ..."
./configure
make

# Build web
echo "Generating manuals ..."
cd manual
make web

As per the new API requirements, the manual/src/html_processing/Makefile variables are updated as follows:

WEBDIRMAN = $(WEDBIR)/$(VERSION)
WEBDIRAPI = $(WEBDIRMAN)/API

Accordingly, we have also updated the manual/src/html_processing/src/common.ml.in file OCaml variables to reflect the required changes:

let web_dir = Filename.parent_dir_name // "webman" // ocaml_version

let docs_maindir = web_dir

let api_page_url = "api"

let manual_page_url = ".."

We also include the https://plausible.ci.dev/js/script.js script to collect view metrics for the HTML pages. The manuals from 3.12 through 5.2 are now available in the https://github.com/ocaml-web/html-compiler-manuals/tree/main GitHub repository.

OCaml.org

The OCaml.org Dockerfile has a step included to clone the HTML manuals and perform an automated production deployment as shown below:

RUN git clone https://github.com/ocaml-web/html-compiler-manuals /manual

ENV OCAMLORG_MANUAL_PATH /manual

The path to the new GitHub repository has been updated in the configuration file, along with the explicit URL paths to the respective manuals. The v2 URLs from the data/releases/*.md file have been replaced without the v2 URLs, and the manual /releases/ redirects have been removed from redirection.ml. The /releases/ redirects are now handled in middleware.ml. The caddy configuration to allow the redirection of v2.ocaml.org can be implemented as follows:

v2.ocaml.org {
	redir https://ocaml.org{uri} permanent
}

Call to Action

You are encouraged to checkout the latest OCaml compiler from trunk and use the build-compiler-html-manual.sh script to generate the HTML documentation.

Please do report any errors or issues that you face at the following GitHub repository: https://github.com/ocaml-web/html-compiler-manuals/issues

If you are interested in working on OCaml.org, please message us on the OCaml Discord server or reach out to the contributors in GitHub.

References

1. (cross-ref) Online OCaml Manual: there should be an easy way to get a fixed-version URL. https://github.com/ocaml/ocaml.org/issues/534

2. Use webman/*.html and webman/api for OCaml.org manuals. https://github.com/ocaml/ocaml/pull/12976

3. Serve OCaml Compiler Manuals. https://github.com/ocaml/ocaml.org/pull/2150

4. Simplify and extend /releases/ redirects from legacy v2.ocaml.org URLs. https://github.com/ocaml/ocaml.org/pull/2448

Tarides is an open-source company first. Our top priorities are to establish and tend to the OCaml community. Similarly, we’re dedicated to the development of the OCaml language and enjoy collaborating with industry partners and individual engineers to continue improving the performance and features of OCaml. We want you to join the OCaml community, test the languages and tools, and actively be part of the language’s evolution.

Tarides is also always happy to discuss commercial opportunities around OCaml. There are many areas where we can help industrial users to adopt OCaml 5 more quickly, including training, support, custom developments, etc. Please contact us if you are interested in discussing your needs.