LizardByte.github.io

The LizardByte website.

About

This repo contains the source files for the LizardByte website.

The page is built using jekyll and hosted on GitHub Pages.

Project discovery

The Projects section reads public repository data from dashboard's github/repos.json and the organization registry. The registry drives organization filtering and the archived-project search. Project search matches repository names, organizations, and descriptions; each card shows its organization.

This consumer requires the multi-org dashboard catalog: banners use dashboard_paths.banner_small, activity and languages use dashboard_key, and Read the Docs links match dashboard_aliases. Transfers and renames therefore retain the existing asset URLs. Filtering reuses the rendered cards without fetching their assets again.

Project titles and banners link to a repository's HTTP(S) homepage, or its GitHub page when no valid homepage is configured. Set that field to the project's public site, including its new subdomain. The consumer does not infer a site URL from an organization or repository name.

Shared navigation

url-canonical in _config_theme.yml is the main-site address used by the shared brand, navigation, and footer links. Project pages keep their own url and baseurl for assets and database requests. Read the Docs project previews link to the published main site; previews of the main site override url-canonical with their own version path.

CrowdIn Localization

Reusable Workflow

This repo contains a reusable workflow to allow for building gh-pages subprojects using the same configuration.

---
name: Jekyll CI
permissions:
  contents: read

on:
 pull_request:
   branches:
     - master
   types:
     - opened
     - synchronize
     - reopened

concurrency:
 group: "${{ github.workflow }}-${{ github.ref }}"
 cancel-in-progress: true

jobs:
  prep:
    runs-on: ubuntu-latest
    steps:
      # Prepare your site here if needed, you can run any build steps needed to generate the site
      # The structure of the artifacts must be exactly as you expect to find the files in the final site
      # e.g. `index.html` should be at the root of the artifact, not in a subdirectory
      - name: Sample build
        run: echo "Hello, world!" > hello.txt

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: prep  # any name except 'site' is allowed
          path: hello.txt
          if-no-files-found: error
          include-hidden-files: true
          retention-days: 1

  call-jekyll-build:
    needs: prep
    uses: LizardByte/LizardByte.github.io/.github/workflows/jekyll-build.yml@master
    secrets:
      GH_BOT_EMAIL: ${{ secrets.GH_BOT_EMAIL }}
      GH_BOT_TOKEN: ${{ secrets.GH_BOT_TOKEN }}
    with:
      gh_bot_name: ${{ vars.GH_BOT_NAME }}
      site_artifact: 'prep'  # any name except 'site' is allowed
      target_branch: 'gh-pages'
      clean_gh_pages: true

For additional options see jekyll-build.yml

PR Previews

Changes to gh-pages can be previewed, by setting up the project in ReadTheDocs. It is recommended to use the following manual configuration:

Initial setup:

Name: LizardByte-gh-pages-<repo_name>  # the project slug cannot be changed after creation
Repository URL: https://github.com/LizardByte/<repo_name>.git
Default-branch: master
Language: English

Project Settings:

Connected-repository: https://github.com/LizardByte/<repo_name>.git
URL-versioning-scheme: Multiple versions without translations
Path-for-.readthedocs.yaml:  # only set if not in the root of the repo
Programming-Language: Other
Project-homepage: https://app.lizardbyte.dev/<repo_name>
Description: Preview PRs for gh-pages
Build-pull-requests-for-this-project: true

Environment Variables:

# REQUIRED
GITHUB_WORKFLOW: call-jekyll-build / Build Jekyll
SITE_ARTIFACT: prep.zip  # the name of the artifact to look for in the workflow

# OPTIONAL
CONFIG_FILE: _config.yml
EXTRACT_ARCHIVE: pre_built_database.zip  # if there is a nested archive to extract
GITHUB_TIMEOUT: 10  # timeout in minutes to use when searching for GitHub artifacts, max 15
THEME_REF: master

Additionally, do the following:

1. Deactivate the stable version
2. Make the latest version hidden
3. Update branch protection rules in GitHub repo settings to require status checks from ReadTheDocs
4. Add the below .readthedocs.yaml file to the root of the repo, or a custom path as specified in the project settings

---
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

version: 2

build:
  os: ubuntu-24.04
  tools:
    ruby: "3.3"
  apt_packages:
    - 7zip
    - jq
  jobs:
    install:
      - |
        mkdir -p "./tmp"
        branch="master"
        base_url="https://raw.githubusercontent.com/LizardByte/LizardByte.github.io"
        url="${base_url}/refs/heads/${branch}/scripts/readthedocs_build.sh"
        curl -sSL -o "./tmp/readthedocs_build.sh" "${url}"
        chmod +x "./tmp/readthedocs_build.sh"
    build:
      html:
        - "./tmp/readthedocs_build.sh"