Skip to content

Commit c0000f4

Browse files
ZnPdCoZnPdCo
authored
feat(docs): update manual (#265)
* feat(*): update docs * upd * add online version * use astro * fix ci * add push event name check * fix * add example * fix * upd * use jsx make image better * add linux help * upd * upd * compile pdf * feat(build-manual.yml): add manual build ci * fix * use setup-typst action * upd * fix yml
1 parent 56c5b1b commit c0000f4

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+8283
-812
lines changed

‎.github/workflows/build-manual.yml‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
name: Build Typst manual and upload artifact
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
paths:
8+
- 'manual/**'
9+
pull_request:
10+
branches:
11+
- master
12+
paths:
13+
- 'manual/**'
14+
workflow_dispatch:
15+
16+
permissions:
17+
contents: write
18+
19+
env:
20+
FONT_DIR: ".fonts"
21+
FONT_VERSION: "v1"
22+
23+
jobs:
24+
build-and-upload:
25+
runs-on: ubuntu-latest
26+
steps:
27+
- uses: actions/checkout@v5
28+
with:
29+
fetch-depth: 0
30+
31+
- uses: actions/cache@v4
32+
with:
33+
path: ${{ env.FONT_DIR }}
34+
key: fonts-${{ runner.os }}-${{ env.FONT_VERSION }}
35+
36+
- name: Install dependencies
37+
run: |
38+
sudo apt-get update -y
39+
sudo apt-get install -y curl unzip
40+
41+
- name: Create font dir
42+
run: |
43+
mkdir -p "${{ env.FONT_DIR }}"
44+
45+
- name: Download Noto Serif CJK SC
46+
run: |
47+
curl -fL "https://github.com/notofonts/noto-cjk/releases/download/Serif2.003/09_NotoSerifCJKsc.zip" -o "${{ env.FONT_DIR }}/noto-serif-sc.zip"
48+
49+
- name: Download Noto Sans CJK SC
50+
run: |
51+
curl -fL "https://github.com/notofonts/noto-cjk/releases/download/Sans2.004/08_NotoSansCJKsc.zip" -o "${{ env.FONT_DIR }}/noto-sans-sc.zip"
52+
53+
- name: Download LXGW WenKai
54+
run: |
55+
curl -fL "https://github.com/lxgw/LxgwWenKai/releases/download/v1.521/lxgw-wenkai-v1.521.zip" -o "${{ env.FONT_DIR }}/lxgw-wenkai.zip"
56+
57+
- name: Download Courier Prime Code
58+
run: |
59+
curl -fL "https://quoteunquoteapps.com/courierprime/downloads/courier-prime-code.zip" -o "${{ env.FONT_DIR }}/courier-prime-code.zip"
60+
61+
- name: Install font
62+
run: |
63+
# Unzip everything
64+
for z in "${{ env.FONT_DIR }}"/*.zip; do
65+
[ -f "$z" ] || continue
66+
echo "Unzipping $z"
67+
unzip -o "$z" -d "${{ env.FONT_DIR }}" || true
68+
done
69+
sudo mkdir -p /usr/local/share/fonts/typst/
70+
sudo cp -r "${{ env.FONT_DIR }}" /usr/local/share/fonts/typst
71+
sudo fc-cache -f -v
72+
73+
- uses: actions/cache@v4
74+
with:
75+
path: ${{ env.FONT_DIR }}
76+
key: fonts-${{ runner.os }}-${{ env.FONT_VERSION }}
77+
78+
- uses: typst-community/setup-typst@v4
79+
80+
- name: Build manual
81+
run: |
82+
typst compile "manual/src/content/manual.typ" "manual/llmanual.pdf" --features html
83+
84+
- name: Upload PDF
85+
uses: actions/upload-artifact@v4
86+
with:
87+
name: llmanual.pdf
88+
path: manual/llmanual.pdf

‎.github/workflows/deploy-manual.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Deploy Manual
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
pull_request:
8+
branches:
9+
- master
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: write
14+
15+
jobs:
16+
build:
17+
runs-on: ubuntu-latest
18+
19+
steps:
20+
- uses: actions/checkout@v5
21+
with:
22+
fetch-depth: 0
23+
24+
- uses: actions/setup-node@v4
25+
with:
26+
node-version: 24
27+
cache: 'npm'
28+
cache-dependency-path: manual/package-lock.json
29+
30+
- name: Install dependencies
31+
run: npm ci
32+
working-directory: ./manual
33+
34+
- name: Build
35+
run: npm run build
36+
working-directory: ./manual
37+
38+
- name: Create nojekyll
39+
run: echo > ./manual/dist/.nojekyll
40+
41+
- name: Deploy to gh-pages
42+
if: ${{ github.event_name == 'push' }}
43+
uses: peaceiris/actions-gh-pages@v4
44+
with:
45+
github_token: ${{ secrets.GITHUB_TOKEN }}
46+
publish_dir: ./manual/dist
47+
force_orphan: true

‎manual/.gitignore‎

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,21 @@
1-
*.aux
2-
*.log
3-
*.out
4-
*.toc
5-
*.xdv
6-
*.fdb_latexmk
7-
*.fls
8-
*.pyg
1+
# build output
2+
dist/
3+
# generated types
4+
.astro/
5+
6+
# dependencies
7+
node_modules/
8+
9+
# logs
10+
npm-debug.log*
11+
yarn-debug.log*
12+
yarn-error.log*
13+
pnpm-debug.log*
14+
15+
16+
# environment variables
17+
.env
18+
.env.production
19+
20+
# macOS-specific files
21+
.DS_Store

‎manual/README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# LemonLime 用户手册
2+
3+
该文件夹储存 LemonLime 用户手册源代码。
4+
5+
用户手册使用 Typst 编写，源代码储存于 `manual/src/content` 目录中。
6+
7+
用户手册有两种分发模式：线上分发与线下分发。
8+
9+
线下分发需要手动编译 Typst 文件，在此之前，你需要下载以下字体：
10+
11+
- [Noto Serif CJK SC](https://github.com/notofonts/noto-cjk/releases/tag/Serif2.003)
12+
- [Noto Sans CJK SC](https://github.com/notofonts/noto-cjk/releases/tag/Sans2.004)
13+
- [LXGW WenKai](https://github.com/lxgw/LxgwWenKai/releases)
14+
- [Courier Prime Code](https://quoteunquoteapps.com/courierprime/downloads/courier-prime-code.zip)
15+
16+
然后使用 Typst CLI 或者 Tinymist Typst 编译 `manual/src/content/manual.typ`，将生成出来的 pdf 重命名并放在 `manual/llmanual.pdf`。注意，需要开启 `--features html`。
17+
18+
如果只是小幅度的修改，也可以在网页端的 artifact 内获取由 CI 编译的 pdf 直接替换。
19+
20+
线上分发使用使用 astro+[astro-typst](https://github.com/OverflowCat/astro-typst)+[starlight theme](https://starlight.astro.build/) 部署于线上。
21+
22+
`docs` 文件夹下的文件：
23+
24+
- `manual.typ`：手册文件，include 了所有文章，供 pdf 导出使用；
25+
- `lib.typ`：手册文件的样式，供 pdf 导出使用；
26+
- `html.typ`：网页文件的一些 hook，劫持了数学公式、图片、标题（网页中不显示标题，因为已经有一个了），其中图片通过调用 JSX 组件 `<Image>` 实现，未来 astro-typst 的 API 可能会更换，需要及时更改。由于 `<Image>` 必须提供 `alt`，在文件中插入图片时必须包含 `alt`。

‎manual/astro.config.mjs‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
// @ts-check
2+
import { defineConfig } from 'astro/config';
3+
import starlight from '@astrojs/starlight';
4+
import { typst } from 'astro-typst';
5+
6+
// https://astro.build/config
7+
export default defineConfig({
8+
site: 'https://project-lemonlime.github.io',
9+
base: 'Project_LemonLime',
10+
integrations: [
11+
starlight({
12+
title: 'LemonLime Manual',
13+
tableOfContents: false,
14+
favicon: '/favicon.png',
15+
social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/Project-LemonLime/Project_LemonLime' }],
16+
sidebar: [
17+
{
18+
label: 'Manual',
19+
items: [
20+
{ label: '快速开始', slug: 'quickstart' },
21+
{ label: '简介', slug: 'intro' },
22+
{ label: '安装', slug: 'install' },
23+
{ label: '设置', slug: 'settings' },
24+
{ label: '比赛', slug: 'contest' },
25+
{ label: '测试', slug: 'judge' },
26+
{ label: '比赛统计', slug: 'statistics' },
27+
{ label: '常见问题及回答', slug: 'issue' },
28+
],
29+
},
30+
],
31+
}),
32+
typst({
33+
options: {
34+
remPx: 14,
35+
},
36+
target: "html",
37+
}),
38+
],
39+
});

‎manual/latexmkrc‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎manual/llmanual.pdf‎

503 KB
Binary file not shown.

0 commit comments

Comments
 (0)