Skip to content

README.md

Latest commit

 

History

History
181 lines (123 loc) · 4.76 KB

README.md

File metadata and controls

181 lines (123 loc) · 4.76 KB

GL.iNet Documentation

This repository contains the source files for GL.iNet router firmware 4.x documentation.

It is now a multilingual documentation repository. The current language sites in this repo are:

  • English: docs/en/
  • German: docs/de/
  • Spanish: docs/es/
  • Japanese: docs/jp/

Each language has its own mkdocs.yml, docs/, and overrides/ directory.

Environment

The documentation is built with MkDocs 1.5.3 and the Material for MkDocs theme 9.4.6.

Installation

Create a Python virtual environment:

python -m venv .venv

Activate the virtual environment, then install dependencies:

pip install -r requirements.txt

You can also install Material for MkDocs directly:

pip install mkdocs-material

Reference: https://squidfunk.github.io/mkdocs-material/getting-started/#with-pip

Repository Structure

The root docs/ folder contains one MkDocs project per language:

docs/
  en/
    mkdocs.yml
    docs/
    overrides/
  de/
    mkdocs.yml
    docs/
    overrides/
  es/
    mkdocs.yml
    docs/
    overrides/
  jp/
    mkdocs.yml
    docs/
    overrides/

In most cases, localized pages should mirror the corresponding English page path under docs/en/docs/.

Local Preview

Run MkDocs against the language you want to preview.

Examples:

mkdocs serve -f docs/en/mkdocs.yml
mkdocs serve -f docs/de/mkdocs.yml
mkdocs serve -f docs/es/mkdocs.yml
mkdocs serve -f docs/jp/mkdocs.yml

If you are reviewing or translating localized content, open the English source page and the matching localized page side by side in VS Code.

Online View

Published documentation:

Writing Guide

Markdown Syntax

All pages are written in Markdown. For basic syntax, see Markdown Guide.

Open a Link in a New Tab

To open a link in a new tab, add {target="_blank"} at the end of the link.

Image File Type

Prefer PNG unless there is a clear reason to use another format.

Image Lightbox

If an image is large, use PhotoSwipe. See About PhotoSwipe.

Image Size

Use gl-50-desktop, gl-60-desktop, gl-70-desktop, gl-80-desktop, or gl-90-desktop to control image width on desktop.

Example:

![gl.inet enable vpn cascading](https://static.gl-inet.com/docs/router/en/4/tutorials/vpn_cascading/enable_vpn_cascading.png){class="gl-50-desktop"}

Image Shadow Effect

Use {class="glboxshadow"} to add a shadow to an image.

Example:

![tap block](https://static.gl-inet.com/docs/router/en/4/tutorials/how-to-block-client-devices/tap-block.jpeg){class="glboxshadow"}

Image Captions

<figure>
  <img src="https://dummyimage.com/600x400/eee/aaa" width="300" />
  <figcaption>Image caption</figcaption>
</figure>

Internal Links

Use relative paths for internal links.

[easytethering](../../../tutorials/tether)

About PhotoSwipe

This project currently uses PhotoSwipe v4. Version 5 looks better, but it requires loading JavaScript modules and is not integrated here.

Use PhotoSwipe when the image width is larger than 1021 px.

<div class="gl-lightbox" itemscope itemtype="http://schema.org/ImageGallery">
  <figure
    itemprop="associatedMedia"
    itemscope
    itemtype="http://schema.org/ImageObject"
  >
    <a
      href="https://static.gl-inet.com/docs/router/en/3/setup/gl-b2200/hardware/hardware_1.jpg"
      itemprop="contentUrl"
      data-size="3167x2480"
    >
      <img
        src="https://static.gl-inet.com/docs/router/en/3/setup/gl-b2200/hardware/hardware_1.jpg"
        itemprop="thumbnail"
        alt="gl-b2200 pcb pinout"
      />
    </a>
  </figure>
</div>

Reference:

About Versioning

The mike plugin is designed for versioned MkDocs deployments, usually with GitHub Pages. This repository does not deploy with GitHub Pages, but it follows a similar output structure.

Reference: