Rework on project structure and CI/CD

.chktexrc

@@ -0,0 +1,10 @@
+# The pandoc templates use hyphens in URLs/HTML comments and unbalanced
+# $...$ control sequences; silence the dash and math-mode noise they cause.
+HyphDash { 1 3 }
+
+CmdLine
+{
+    -n16
+    -n25
+    -n36
+}

.codespellrc

@@ -0,0 +1,4 @@
+[codespell]
+# `figurestyle` is a LaTeX macro name in the third-party Eisvogel template.
+ignore-words-list = figurestyle
+skip = README.md

.github/linters/.jscpd.json

@@ -0,0 +1,7 @@
+{
+  "threshold": 0,
+  "reporters": ["consoleFull"],
+  "absolute": true,
+  "gitignore": true,
+  "ignore": ["README.md", "src/template/**"]
+}

.github/linters/zizmor.yaml

@@ -0,0 +1,15 @@
+# Actions are pinned to version tags (release-please keeps super-linter up to
+# date), which satisfies the "ref-pin" policy for these sources.
+rules:
+  # The publish workflow deliberately uses action-gh-release instead of the
+  # `gh release` CLI; this is an informational, non-failing finding.
+  superfluous-actions:
+    disable: true
+  unpinned-uses:
+    config:
+      policies:
+        actions/*: ref-pin
+        super-linter/*: ref-pin
+        softprops/*: ref-pin
+        EndBug/*: ref-pin
+        googleapis/*: ref-pin

.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: ci
+
+on:
+  push:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    permissions:
+      # contents permission to clone the repository
+      contents: read
+      packages: read
+      # issues and pull-requests permissions to write results as pull
+      # request comments. Omit them if you don't need summary comments
+      issues: write
+      pull-requests: write
+      # To report GitHub Actions status checks. Omit if you don't need
+      # to update commit status
+      statuses: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+        with:
+          # super-linter needs the full git history to get the
+          # list of files that changed across commits
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Super-linter
+        uses: super-linter/super-linter@v9.0.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.ACTIONS_GH_TOKEN }}
+          FILTER_REGEX_EXCLUDE: '(^|/)README\.(md|pdf)$'
+          VALIDATE_BIOME_FORMAT: "false"
+          VALIDATE_BIOME_LINT: "false"

.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: publish
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - name: Install pandoc
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y pandoc texlive texlive-latex-extra texlive-fonts-extra texlive-fonts-recommended
+      - name: Make docs
+        run: make all
+      - name: Release MD and PDF
+        uses: softprops/action-gh-release@v3
+        with:
+          working_directory: dist
+          body_path: CHANGELOG.md

.github/workflows/readme.yml

@@ -0,0 +1,29 @@
+name: readme
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  readme:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # release events check out a tag in detached HEAD, where
+          # add-and-commit cannot push; check out the default branch instead
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+      - name: Install pandoc
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y pandoc
+      - name: Generate README.md
+        run: make readme
+      - name: Commit README.md
+        uses: EndBug/add-and-commit@v11
+        with:
+          add: README.md
+          message: "docs(README): update generated documentation"

.github/workflows/release-please.yml

@@ -0,0 +1,19 @@
+name: release-please
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v5
+        with:
+          token: ${{ secrets.ACTIONS_GH_TOKEN }}
+          release-type: simple

.gitignore

@@ -1,2 +1,4 @@
-./*.pdf
-./*.md
+node_modules/
+
+# Generated
+dist/

.markdownlintignore

@@ -0,0 +1,3 @@
+# Generated files
+README.md
+dist/

.pre-commit-config.yaml

@@ -0,0 +1,42 @@
+repos:
+  - repo: local
+    hooks:
+      - id: textlint
+        language: system
+        name: Run tests
+        entry: npx -y -p textlint -p textlint-rule-terminology -p textlint-filter-rule-comments textlint -c .textlintrc.json
+        stage: [commit]
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.3
+    hooks:
+      - id: codespell
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: ""
+    hooks:
+      - id: prettier
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.49.1
+    hooks:
+      - id: markdownlint-fix
+  - repo: https://github.com/meliache/pre-commit-chktex
+    rev: v0.2.2
+    hooks:
+      - id: chktex-system # install and use chktex via a conda
+      # alternative: use the following line to use the system chktex
+      # - id: chktex-system
+  - repo: https://github.com/jorisroovers/gitlint
+    rev: v0.19.1
+    hooks:
+      - id: gitlint
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: detect-private-key
+      - id: fix-byte-order-marker
+      - id: mixed-line-ending
+      - id: end-of-file-fixer
+      - id: trailing-whitespace

.prettierignore

@@ -0,0 +1,3 @@
+# Generated files
+README.md
+dist

.textlintignore

@@ -0,0 +1,4 @@
+README.md
+README.pdf
+
+dist/

.textlintrc.json

@@ -0,0 +1,9 @@
+{
+  "plugins": {},
+  "filters": {
+    "comments": true
+  },
+  "rules": {
+    "terminology": true
+  }
+}

Makefile

@@ -1,24 +1,46 @@
-SRC_DIR			:= src
-SRC 			:= \
-					$(SRC_DIR)/README.md
-TEMPLATE_MD		:= $(SRC_DIR)/template/md.tex
-TEMPLATE_PDF	:= $(SRC_DIR)/template/pdf.tex
-MD_FILES		:= $(patsubst $(SRC_DIR)/%.md,%.md,$(SRC))
-PDF_FILES 		:= $(patsubst $(SRC_DIR)/%.md,%.pdf,$(SRC))
+SRC_DIR      := src
+DIST_DIR     := dist
 
-all: $(MD_FILES) $(PDF_FILES)
+SRC          := \
+                $(SRC_DIR)/manual.md
 
-%.md: $(SRC_DIR)/%.md
+TEMPLATE_README_MD  := $(SRC_DIR)/template/readme_md.tex
+TEMPLATE_MD  := $(SRC_DIR)/template/md.tex
+TEMPLATE_PDF := $(SRC_DIR)/template/pdf.tex
+
+MD_FILES     := $(patsubst $(SRC_DIR)/%.md,$(DIST_DIR)/%.md,$(SRC))
+PDF_FILES    := $(patsubst $(SRC_DIR)/%.md,$(DIST_DIR)/%.pdf,$(SRC))
+
+all: markdown pdf readme
+.PHONY: all
+
+markdown: $(MD_FILES)
+.PHONY: markdown
+
+pdf: $(PDF_FILES)
+.PHONY: pdf
+
+readme: README.md
+.PHONY: readme
+
+README.md: $(SRC_DIR)/manual.md
+	mkdir -p $(dir $@)
+	pandoc --template $(TEMPLATE_README_MD) -t gfm --toc $< -o $@
+
+$(DIST_DIR)/%.md: $(SRC_DIR)/%.md
 	mkdir -p $(dir $@)
-	pandoc --template $(TEMPLATE_MD) -t gfm --shift-heading-level-by=1 --toc $< -o $@
+	pandoc --template $(TEMPLATE_MD) -t gfm --toc $< -o $@
 
-%.pdf: $(SRC_DIR)/%.md
+$(DIST_DIR)/%.pdf: $(SRC_DIR)/%.md
 	mkdir -p $(dir $@)
 	pandoc --template $(TEMPLATE_PDF) $< -o $@
 
 clean:
-	rm -f $(MD_FILES) $(PDF_FILES)
+	rm -rf $(DIST_DIR) README.md
+.PHONY: clean
 
 re: clean all
+.PHONY: re
 
-.PHONY: docs clean re
+init:
+	@uv run --with pre-commit pre-commit install