openvidu-docs

• Development
• Docs writing guidelines
  • Branches
  • Adding a new page
  • Adding a new shared snippet
  • Mkdocs Material tag system
    • Theme-dependent images/videos
• Versioning
• Versioning with GitHub Actions
  • Publishing a new version
  • Overwriting the latest version
  • Overwriting a past version
• Versioning locally
  • Prerequisites
  • Publishing a new version
  • Overwriting the latest version
  • Overwriting a past version
  • Understanding the versioning script
• Testing versioning locally
• Sync changes between openvidu.io and livekit-tutorials.openvidu.io

Development

This documentation is built with MkDocs Material.

1. Create custom Docker image with necessary extra plugins:

docker build --pull --no-cache --rm=true -t squidfunk/mkdocs-material .

2. Serve the documentation:

docker run --name=mkdocs --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

3. Build the documentation:

docker run --rm -it -v ${PWD}:/docs -e GOOGLE_ANALYTICS_KEY=G-XXXXXXXX squidfunk/mkdocs-material build

Parameters:

• GOOGLE_ANALYTICS_KEY: Google Analytics key to track page views. This is the MEASUREMENT ID of the web stream details.

Docs writing guidelines

Branches

If you are writing documentation for the current version in development, push commits to the next branch. On new releases, this branch will be merged to main by an OpenVidu developer

Adding a new page

When creating a new page, follow these steps:

1. Create the Markdown file:
   Place a .md file in the appropriate folder under the docs directory.

2. Add metadata:
   Include the following metadata at the beginning of the file:

   ---
   title: Example # Unique title (only required if the title in "mkdocs.yml" is not unique or missing)
   description: Some description # Unique description, max 160 characters
   ---

3. Reference in mkdocs.yml:
   Two changes must be made:

   • Add the new page to the nav section in mkdocs.yml (if you want to include it in the navigation) and set the title.

   • Include the page (relative to the docs folder) in mkdocs.yml in the mkdocs-llmstxt plugin configuration, under the corresponding section (OpenVidu for non-versioned generic pages, OpenVidu Meet or Platform for versioned pages specific to the corresponding technology):

     plugins:
       - llmstxt:
           markdown_description: Self-hosted videoconference solution and SDK
           sections:
             OpenVidu Meet:
             - meet/newpage.md: Brief description # copy here the description from the metadata of the .md file.

4. Update custom versioning scripts (if needed):

   • Non-versioned pages: If the new page is not versioned, add it to the NON_VERSIONED_PAGES array in the push-new-version.sh script.
   • Versioned pages: If the new page is part of a new set of versioned pages, add it to the VERSIONED_PAGES array in the push-new-version.sh script.

If the new page contains links to other pages, take into account the following:

• Markdown links: Use relative paths pointing to the Markdown file (including the .md extension).
• HTML links: Use relative paths pointing to the folder containing the HTML file. Keep in mind that, after building the documentation, the HTML files will be placed in a folder with the same name as the Markdown file (except index.md files, which will be placed in its parent folder as index.html). For example, if you have a Markdown file performance.md, it will be built to performance/index.html. Therefore, you must add an extra ../ to the path to point to the correct folder unless the markdown file from which you are linking is named index.md.

Important

Links to non-versioned pages must be absolute paths (e.g. /pricing/).

Note

When serving the site locally using mkdocs-material, there should be no warnings about links except for using absolute paths to non-versioned pages.

Adding a new shared snippet

When creating a new shared snippet, follow these steps:

1. Create the Markdown file:
   Place a .md file in the shared directory.

2. Reference in a page: Use the following syntax to include the snippet in other snippets or pages:

   --8<-- "shared/snippet.md"

Note

The path is relative to the root of the repository.

Important

If the new snippet contains links to other pages, the same rules as for pages apply. Since the release of Mkdocs 1.6, it is possible to use absolute links to other pages, and Mkdocs will make them relative to the docs_dir root folder thanks to this configuration options in mkdocs.yml. So, now any document (e.g. "dir1/foo.md") can link to the document "dir2/bar.md" as [link](/dir2/bar.md), in addition to the previously only correct way [link](../dir2/bar.md).

This allows to use local links in shared snippets that are embedded in pages with different hierarchy!.

Mkdocs Material tag system

We use a tag system to determine which JS scripts should be included and run for each page:

---
title: My page
tags:
  - tag1
  - tag2
  - ...
---

These are the tags currently used:

• setupwowjs: add this tag to the page if there are wow.js animations in it (elements with class wow):

  <div class="wow animated animatedFadeInUp fadeInUp">
    ...
  </div>

• setupcardglow: add this tag to the page if there are cards with glow effect in it. The HTML structure of these cards must comply with:

  <div class="feature-cards">
    <div class="grid cards">
      ...
    </div>
  </div>

• setupcarousel: add this tag to the page if there are Flickity carousels in it. The HTML structure of these carousels must comply with:

  <div class="carousel">
    <div class="carousel-cell">
      ...
    </div>
    ...
  </div>

• setupcustomgallery: add this tag to the page if there are custom GLightbox elements in it. This means that if a Markdown page only contains Markdown images (e.g. ![Image description](image-url.jpg)), this tag is not necessary (the default behavior of the plugin mkdocs-glightbox will be used to automatically create the gallery). But if the page contains HTML images or videos marked with the glightbox class, this tag is required. The HTML structure of these elements is like this:

  For images:

  <a class="glightbox" href="image.png" data-type="image" data-desc-position="bottom" data-gallery="gallery1"><img src="image.png" loading="lazy" class="control-height"/></a>

  For videos:

  <a class="glightbox" href="video.mp4" data-type="video" data-desc-position="bottom" data-gallery="gallery1"><video class="round-corners" src="video.mp4" loading="lazy" defer muted playsinline autoplay loop async></video></a>

Theme-dependent images/videos

For images using the default Mkdocs Material syntax (using the #only-dark and #only-light suffixes):

![Image description](image-dark.png#only-dark)
![Image description](image-light.png#only-light)

For images/videos using the custom GLightbox syntax, apart from having tag setupcustomgallery in its page, this must be the HTML structure:

<a class="glightbox" href="image-dark.png" data-type="image" data-desc-position="bottom" data-gallery="gallery1"><img src="image-dark.png#only-dark" loading="lazy" class="round-corners" alt="Image description"/></a>
<a class="glightbox" href="image-light.png" data-type="image" data-desc-position="bottom" data-gallery="gallery1"><img src="image-light.png#only-light" loading="lazy" class="round-corners" alt="Image description"/></a>

• The #only-dark and #only-light suffixes must be present in the src attribute of the <img> or <video> elements, but NOT in the href attribute of the <a> parent element.
• It is important that each HTML <a> element is a one-liner. There are some strange behaviors when they are not.

Versioning

MkDocs Material uses the mike tool for versioning. mike uses GitHub pages to host the documentation, and builds each version on branch gh-pages.

The repository must be using MkDocs Material and must be properly setup like explained here. This proper setup includes the following points:

• Adding extra.version.provider: mike to mkdocs.yml.
• Properly configuring the default alias like extra.version.default: latest in mkdocs.yml.
• Adding extra.version.alias: true to mkdocs.yml (just to show the default alias tag next to the version selector).
• Properly configuring site_url in mkdocs.yml to the actual domain name in which the docs will be served (this allows staying on the same path when switching versions).

These configurations get the repository ready for versioning.

Versioning with GitHub Actions

Run action Publish Web:

Publishing a new version

• Select the script to execute: push-new-version.sh
• Version to publish: 3.0.0

Overwriting the latest version

• Select the script to execute: overwrite-latest-version.sh
• Version to publish: 3.0.0

Overwriting a past version

• Select the script to execute: overwrite-past-version.sh
• Version to publish: 3.0.0

Versioning locally

Prerequisites

• mike:

  pip install mike

• Packages mkdocs-material and mkdocs-glightbox:

  pip install mkdocs-material mkdocs-glightbox

Publishing a new version

This script publishes a new version, updates alias "latest" to point to this new version, and updates the non-versioned files at root.

It also creates a new branch from main named after the version (e.g. 3.0.0) and pushes it to the repository. This allows modifying past versions if required later.

cd custom-versioning
./push-new-version.sh 3.0.0

Overwriting the latest version

This script overwrites the content of the latest published version, also updating the non-versioned files at root.

It also updates the version branch with any new commits available in main branch (with a git rebase). This keeps the latest version branch up to date with the latest changes in main.

cd custom-versioning
./overwrite-latest-version.sh 3.0.0

Overwriting a past version

This script overwrites the content of a specific past version without touching the non-versioned files at root.

In this case, all the changes to be published must be already commited into the version branch before calling this script.

cd custom-versioning
./overwrite-past-version.sh 3.0.0

Understanding the versioning script

Script push-new-version.sh performs the following steps:

1. Deploy a new version of the documentation with mike.
2. Change links in versioned HTML files (docs and meet) from new version that point to non-versioned files (home, support, pricing...) accessible from "/" to use absolute paths (e.g. /pricing/).
3. Change links in non-versioned HTML files from new version that point to versioned files to use absolute paths to the latest version (e.g. /latest/docs/).
4. Remove version from links that point to non-versioned files in the new version.
5. Update llms.txt file: replace version with 'latest' for versioned pages and remove version from non-versioned pages.
6. Move non-versioned files from the new version to root. This keeps the global pages served on "/" always updated to the latest published version.
7. Update sitemap.xml: copy it from the version folder to root, replace version with 'latest' for versioned pages, remove version from non-versioned pages, and generate the compressed sitemap.xml.gz file.
8. Add a redirection HTML file to the root of the new version to redirect to the docs index page (docs/).

Note

The overwriting of the non-versioned files located at root of gh-pages branch (points 3, 4, 5, 6 and 7) is done by default. To avoid overriding these files, call the script adding false as second argument: ./push-new-version.sh 3.0.0 false. Script overwrite-past-version.sh does this to only overwrite the files of that specific past version without affecting the root non-versioned files.

Testing versioning locally

This will serve the content of gh-pages branch locally:

mike serve

To build a new version without pushing to GitHub:

mike deploy 3.0.0

Sync changes between openvidu.io and livekit-tutorials.openvidu.io

Whenever any changes are made to the tutorials documentation, theses changes must be also reflected in repository livekit-tutorials-docs so they end up available in livekit-tutorials.openvidu.io.

To apply changes in the web livekit-tutorials.openvidu.io:

• In this repository, push the changes to tutorials documentation to the main branch and run GitHub Action to overwrite the latest version.
• In repository livekit-tutorials-docs, push the changes to the main branch and run action Publish Web selecting the main branch.