Try mkdocs-macro-plugin with Debian and Ubuntu, close #244

ustclug · Apr 20, 2024 · e0d77a0 · e0d77a0
1 parent aab96db
commit e0d77a0
Show file tree

Hide file tree

Showing 5 changed files with 147 additions and 47 deletions.
diff --git a/docs/debian-security.md b/docs/debian-security.md
@@ -36,12 +36,44 @@ Debian Old Old Stable, Old Stable, Stable
 
 可以直接使用如下命令完成上述修改：
 
-    sudo sed -i 's|security.debian.org/debian-security|mirrors.ustc.edu.cn/debian-security|g' /etc/apt/sources.list
+    sudo sed -i 's|security.debian.org|mirrors.ustc.edu.cn|g' /etc/apt/sources.list
 
-当然也可以直接编辑 `/etc/apt/sources.list` 文件（需要使用 sudo）。以下是 Debian Stable 参考配置内容：
+当然也可以直接编辑 APT 源文件（需要使用 sudo）。以下是参考配置内容：
 
-    deb http://mirrors.ustc.edu.cn/debian-security/ stable-security main non-free contrib
-    # deb-src http://mirrors.ustc.edu.cn/debian-security/ stable-security main non-free contrib
+{% for release in debian_releases %}
+
+{% set debian_suites = "main contrib non-free" %}
+{% if release.version >= 12 %}
+{% set debian_suites = debian_suites + " non-free-firmware" %}
+{% endif %}
+
+{% set debian_security = release.codename + "-security" %}
+{% if release.version < 11 %}
+{% set debian_security = release.codename + "/updates" %}
+{% endif %}
+
+=== "Debian {{ release.version }}"
+
+    === "`sources.list` 格式"
+
+        ```shell title="/etc/apt/sources.list"
+        deb http://mirrors.ustc.edu.cn/debian-security/ {{ debian_security }} {{ debian_suites }}
+        # deb-src http://mirrors.ustc.edu.cn/debian-security/ {{ debian_security }} {{ debian_suites }}
+        ```
+
+    === "DEB822 格式"
+
+        ```yaml title="/etc/apt/sources.list.d/debian.sources"
+        Types: deb
+        URIs: https://mirrors.ustc.edu.cn/debian-security
+        Suites: {{ debian_security }}
+        Components: {{ debian_suites }}
+        ```
+
+        如果需要使用源码仓库，可以在 Types 中添加 `deb-src`。
+
+        如果需要使用 backports 软件源，可以在 Suites 中添加 `{{ release.codename }}-backports`。
+{% endfor %}
 
 更改完 `sources.list` 文件后请运行 `sudo apt-get update` 更新索引以生效。
 

diff --git a/docs/debian.md b/docs/debian.md
@@ -24,24 +24,62 @@ Debian Old Stable, Stable, Testing, Unstable(sid)
 
     操作前请做好相应备份。
 
-一般情况下，将 `/etc/apt/sources.list`
-文件中 Debian 默认的源地址 `http://deb.debian.org/` 替换为
-`http://mirrors.ustc.edu.cn` 即可。
+一般情况下，将 `/etc/apt/sources.list` 文件中 Debian 默认的源地址 `http://deb.debian.org/` 替换为 `http://mirrors.ustc.edu.cn` 即可。
 
 可以使用如下命令：
 
     sudo sed -i 's/deb.debian.org/mirrors.ustc.edu.cn/g' /etc/apt/sources.list
 
-当然也可以直接编辑 `/etc/apt/sources.list` 文件（需要使用 sudo）。
-以下是 Debian Stable 参考配置内容：
+当然也可以直接编辑 APT 源文件（需要使用 sudo）。以下是参考配置内容：
 
-    deb http://mirrors.ustc.edu.cn/debian stable main contrib non-free non-free-firmware
-    # deb-src http://mirrors.ustc.edu.cn/debian stable main contrib non-free non-free-firmware
-    deb http://mirrors.ustc.edu.cn/debian stable-updates main contrib non-free non-free-firmware
-    # deb-src http://mirrors.ustc.edu.cn/debian stable-updates main contrib non-free non-free-firmware
+{% for release in debian_releases %}
 
-    # deb http://mirrors.ustc.edu.cn/debian stable-proposed-updates main contrib non-free non-free-firmware
-    # deb-src http://mirrors.ustc.edu.cn/debian stable-proposed-updates main contrib non-free non-free-firmware
+{% set debian_suites = "main contrib non-free" %}
+{% if release.version >= 12 %}
+{% set debian_suites = debian_suites + " non-free-firmware" %}
+{% endif %}
+
+{% set debian_security = release.codename + "-security" %}
+{% if release.version < 11 %}
+{% set debian_security = release.codename + "/updates" %}
+{% endif %}
+
+=== "Debian {{ release.version }}"
+
+    === "`sources.list` 格式"
+
+        ```shell title="/etc/apt/sources.list"
+        # 默认注释了源码仓库，如有需要可自行取消注释
+        deb http://mirrors.ustc.edu.cn/debian {{ release.codename }} {{ debian_suites }}
+        # deb-src http://mirrors.ustc.edu.cn/debian {{ release.codename }} {{ debian_suites }}
+        deb http://mirrors.ustc.edu.cn/debian {{ release.codename }}-updates {{ debian_suites }}
+        # deb-src http://mirrors.ustc.edu.cn/debian {{ release.codename }}-updates {{ debian_suites }}
+
+        # backports 软件源，请按需启用
+        # deb http://mirrors.ustc.edu.cn/debian {{ release.codename }}-backports {{ debian_suites }}
+        # deb-src http://mirrors.ustc.edu.cn/debian {{ release.codename }}-backports {{ debian_suites }}
+        ```
+
+    === "DEB822 格式"
+
+        ```yaml title="/etc/apt/sources.list.d/debian.sources"
+        Types: deb
+        URIs: https://mirrors.ustc.edu.cn/debian
+        Suites: {{ release.codename }} {{ release.codename }}-updates
+        Components: {{ debian_suites }}
+        
+        Types: deb
+        URIs: https://mirrors.ustc.edu.cn/debian-security
+        Suites: {{ debian_security }}
+        Components: {{ debian_suites }}
+        ```
+
+        !!! warning "DEB822 格式包含了对 debian-security 源的修改"
+
+        如果需要使用源码仓库，可以在 Types 中添加 `deb-src`。
+
+        如果需要使用 backports 软件源，可以在 Suites 中添加 `{{ release.codename }}-backports`。
+{% endfor %}
 
 !!! tip
 
@@ -58,20 +96,6 @@ Debian Old Stable, Stable, Testing, Unstable(sid)
 
         sudo sed -i 's/deb.debian.org/mirrors.ustc.edu.cn/g' /etc/apt/sources.list.d/debian.sources
 
-    以下是在 Debian 12 容器镜像中**同时修改了 Debian 与 Debian Security 源的情况下**的参考配置内容：
-
-        Types: deb
-        URIs: http://mirrors.ustc.edu.cn/debian
-        Suites: bookworm bookworm-updates
-        Components: main
-        Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg
-
-        Types: deb
-        URIs: http://mirrors.ustc.edu.cn/debian-security
-        Suites: bookworm-security
-        Components: main
-        Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg
-
 同时你也可能需要更改 Debian Security 源，请参考 [debian-security](debian-security.md)。
 
 更改完 `sources.list` 文件后请运行 `sudo apt-get update` 更新索引以生效。

diff --git a/docs/ubuntu.md b/docs/ubuntu.md
@@ -56,32 +56,50 @@ AMD64 (x86_64), Intel x86
     使用 HTTPS 可以有效避免国内运营商的缓存劫持。即
     `sudo sed -i 's/http:/https:/g' /etc/apt/sources.list`。
 
-当然也可以直接编辑 `/etc/apt/sources.list`
- 文件（需要使用 sudo）。以下是 Ubuntu 22.04 参考配置内容：
+当然也可以直接编辑 APT 源文件（需要使用 sudo）。以下是参考配置内容：
 
-    # 默认注释了源码仓库，如有需要可自行取消注释
-    deb https://mirrors.ustc.edu.cn/ubuntu/ jammy main restricted universe multiverse
-    # deb-src https://mirrors.ustc.edu.cn/ubuntu/ jammy main restricted universe multiverse
+=== "`sources.list` 格式"
+{% for release in ubuntu_releases %}
+    === "Ubuntu {{ release.name }}"
 
-    deb https://mirrors.ustc.edu.cn/ubuntu/ jammy-security main restricted universe multiverse
-    # deb-src https://mirrors.ustc.edu.cn/ubuntu/ jammy-security main restricted universe multiverse
+        ```shell title="/etc/apt/sources.list"
+        # 默认注释了源码仓库，如有需要可自行取消注释
+        deb https://mirrors.ustc.edu.cn/ubuntu/ {{ release.codename }} main restricted universe multiverse
+        # deb-src https://mirrors.ustc.edu.cn/ubuntu/ {{ release.codename }} main restricted universe multiverse
 
-    deb https://mirrors.ustc.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse
-    # deb-src https://mirrors.ustc.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse
+        deb https://mirrors.ustc.edu.cn/ubuntu/ {{ release.codename }}-security main restricted universe multiverse
+        # deb-src https://mirrors.ustc.edu.cn/ubuntu/ {{ release.codename }}-security main restricted universe multiverse
 
-    deb https://mirrors.ustc.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse
-    # deb-src https://mirrors.ustc.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse
+        deb https://mirrors.ustc.edu.cn/ubuntu/ {{ release.codename }}-updates main restricted universe multiverse
+        # deb-src https://mirrors.ustc.edu.cn/ubuntu/ {{ release.codename }}-updates main restricted universe multiverse
 
-    # 预发布软件源，不建议启用
-    # deb https://mirrors.ustc.edu.cn/ubuntu/ jammy-proposed main restricted universe multiverse
-    # deb-src https://mirrors.ustc.edu.cn/ubuntu/ jammy-proposed main restricted universe multiverse
+        deb https://mirrors.ustc.edu.cn/ubuntu/ {{ release.codename }}-backports main restricted universe multiverse
+        # deb-src https://mirrors.ustc.edu.cn/ubuntu/ {{ release.codename }}-backports main restricted universe multiverse
 
-更改完 `sources.list` 文件后请运行 `sudo apt-get update` 更新索引以生效。
+        # 预发布软件源，不建议启用
+        # deb https://mirrors.ustc.edu.cn/ubuntu/ {{ release.codename }}-proposed main restricted universe multiverse
+        # deb-src https://mirrors.ustc.edu.cn/ubuntu/ {{ release.codename }}-proposed main restricted universe multiverse
+        ```
+{% endfor %}
 
-!!! tip
+=== "DEB822 格式"
+{% for release in ubuntu_releases %}
+    === "Ubuntu {{ release.name }}"
+
+        ```yaml title="/etc/apt/sources.list.d/ubuntu.sources"
+        Enabled: yes
+        Types: deb
+        URIs: https://mirrors.ustc.edu.cn/ubuntu
+        Suites: {{ release.codename }} {{ release.codename }}-updates {{ release.codename }}-security
+        Components: main restricted universe multiverse
+        ```
 
-    如要用于其他版本，把 jammy 换成其他版本代号即可:
-    22.04：`jammy`；20.04：`focal`；18.04：`bionic`；16.04：`xenial`；14.04：`trusty`。
+        如果需要使用源码仓库，可以在 `Types` 中添加 `deb-src`。
+
+        如果需要使用预发布软件源，可以在 `Suites` 中添加 `{{ release.codename }}-proposed`。
+{% endfor %}
+
+更改完 `sources.list` 文件后请运行 `sudo apt-get update` 更新索引以生效。
 
 另外，也可以使用 snullp 大叔开发的[配置生成器](https://mirrors.ustc.edu.cn/repogen)。
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -60,6 +60,13 @@ markdown_extensions:
   - toc:
       permalink: true
 
+plugins:
+  - search
+  - macros:
+      include_dir: includes
+      j2_comment_start_string: "{%#"
+      j2_comment_end_string: "%}"
+
 extra:
   social:
     - icon: fontawesome/brands/linux
@@ -70,6 +77,24 @@ extra:
     provider: google
     property: UA-160637954-1
 
+  # data for use in templates
+  debian_releases:
+    - version: 12
+      codename: bookworm
+    - version: 11
+      codename: bullseye
+    - version: 10
+      codename: buster
+  ubuntu_releases:
+    - name: 22.04
+      codename: jammy
+    - name: 20.04
+      codename: focal
+    - name: 18.04
+      codename: bionic
+    - name: 16.04
+      codename: xenial
+
 extra_css:
   - css/extra.css
 

diff --git a/requirements.txt b/requirements.txt
@@ -1,3 +1,4 @@
 mkdocs-material
 requests
 jieba
+mkdocs-macros-plugin