Skip to content

Commit 2575ca4

Browse files
MisterBrookTMisterBrookT
authored
Merge pull request #1 from HKUSTDial/ci-docs-initial
Add docs CI + CONTRIBUTING + gitignore
2 parents fb2aded + ee98b4a commit 2575ca4

7 files changed

Lines changed: 186 additions & 0 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
name: docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- "**/*.md"
8+
- ".github/workflows/docs.yml"
9+
- ".markdownlint.json"
10+
- ".markdown-link-check.json"
11+
pull_request:
12+
paths:
13+
- "**/*.md"
14+
- ".github/workflows/docs.yml"
15+
- ".markdownlint.json"
16+
- ".markdown-link-check.json"
17+
workflow_dispatch:
18+
19+
permissions:
20+
contents: read
21+
22+
jobs:
23+
markdownlint:
24+
name: markdownlint
25+
runs-on: ubuntu-latest
26+
timeout-minutes: 5
27+
steps:
28+
- uses: actions/checkout@v4
29+
30+
- uses: actions/setup-node@v4
31+
with:
32+
node-version: "20"
33+
34+
- name: Install markdownlint-cli
35+
run: npm install -g markdownlint-cli@0.41.0
36+
37+
- name: Run markdownlint
38+
run: markdownlint "**/*.md" --ignore node_modules
39+
40+
link-check:
41+
name: link check
42+
runs-on: ubuntu-latest
43+
timeout-minutes: 10
44+
steps:
45+
- uses: actions/checkout@v4
46+
with:
47+
fetch-depth: 0
48+
49+
- name: Collect changed Markdown files
50+
id: changed
51+
env:
52+
EVENT_NAME: ${{ github.event_name }}
53+
BASE_SHA: ${{ github.event.pull_request.base.sha }}
54+
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
55+
BEFORE_SHA: ${{ github.event.before }}
56+
AFTER_SHA: ${{ github.sha }}
57+
run: |
58+
set -euo pipefail
59+
if [ "$EVENT_NAME" = "pull_request" ]; then
60+
files=$(git diff --name-only --diff-filter=AM "$BASE_SHA" "$HEAD_SHA" -- '*.md')
61+
elif [ "$EVENT_NAME" = "push" ] && [ -n "${BEFORE_SHA:-}" ] && [ "$BEFORE_SHA" != "0000000000000000000000000000000000000000" ]; then
62+
files=$(git diff --name-only --diff-filter=AM "$BEFORE_SHA" "$AFTER_SHA" -- '*.md')
63+
else
64+
files=""
65+
fi
66+
{
67+
echo "files<<EOF"
68+
echo "$files"
69+
echo "EOF"
70+
} >> "$GITHUB_OUTPUT"
71+
72+
- name: Install markdown-link-check
73+
if: steps.changed.outputs.files != ''
74+
run: npm install -g markdown-link-check@3.12.2
75+
76+
- name: Run markdown-link-check
77+
if: steps.changed.outputs.files != ''
78+
env:
79+
FILES: ${{ steps.changed.outputs.files }}
80+
run: |
81+
set -uo pipefail
82+
fail=0
83+
while IFS= read -r f; do
84+
[ -z "$f" ] && continue
85+
[ -f "$f" ] || continue
86+
echo "::group::$f"
87+
markdown-link-check -q -c .markdown-link-check.json "$f" || fail=1
88+
echo "::endgroup::"
89+
done <<< "$FILES"
90+
exit $fail

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
node_modules/
2+
.DS_Store
3+
*.log

‎.markdown-link-check.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"timeout": "10s",
3+
"retryOn429": true,
4+
"retryCount": 3,
5+
"fallbackRetryDelay": "30s",
6+
"aliveStatusCodes": [200, 206, 301, 302, 303, 307, 308],
7+
"ignorePatterns": [
8+
{ "pattern": "^https://github.com/user-attachments/assets" },
9+
{ "pattern": "^https://arxiv.org/" },
10+
{ "pattern": "^http://localhost" },
11+
{ "pattern": "^#.*" },
12+
{ "pattern": "^\\./images/demo-hero\\.gif$" }
13+
]
14+
}

‎.markdownlint.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"default": true,
3+
"MD012": false,
4+
"MD013": false,
5+
"MD022": false,
6+
"MD024": { "siblings_only": true },
7+
"MD026": false,
8+
"MD028": false,
9+
"MD031": false,
10+
"MD032": false,
11+
"MD033": false,
12+
"MD034": false,
13+
"MD036": false,
14+
"MD040": false,
15+
"MD041": false
16+
}

‎CONTRIBUTING.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Contributing to DataMagic
2+
3+
Thanks for your interest in DataMagic. The repo is currently **docs-first** —
4+
the production product lives at [datamagic.chat](https://datamagic.chat/), while this
5+
repository holds the public documentation, the published paper artifacts, and the
6+
[`datamagic-video`](./datamagic-video/) skill for AI coding agents.
7+
8+
So contributions today land in one of four buckets:
9+
10+
| Bucket | Examples |
11+
|---|---|
12+
| Docs (Chinese / English) | typo fixes, clearer explanations, broken links, missing context |
13+
| The `datamagic-video` skill | new rule pages, refining narrative patterns, chart-selection guidance, anti-patterns |
14+
| Examples | new input/output examples under `docs/input-output-examples*.md` |
15+
| Infrastructure | CI, link checking, lint config |
16+
17+
Please open an Issue first for anything beyond a small fix so we can align on scope.
18+
19+
## Quick start
20+
21+
```bash
22+
git clone https://github.com/HKUSTDial/DataMagic
23+
cd DataMagic
24+
```
25+
26+
The repo has no build step. To preview your edits, just open the Markdown files
27+
locally (or in your editor's preview pane). To match what CI checks, run:
28+
29+
```bash
30+
# Markdown lint (matches the rules in .markdownlint.json)
31+
npx --yes markdownlint-cli@0.41.0 "**/*.md" --ignore node_modules
32+
33+
# Link check on a single file
34+
npx --yes markdown-link-check@3.12.2 -c .markdown-link-check.json README.md
35+
```
36+
37+
## Style
38+
39+
- Keep both `README.md` (中文) and `README.en.md` (English) in sync when editing
40+
shared sections (links, badges, examples, roadmap).
41+
- For per-doc Chinese / English pairs under `docs/`, edit both files in the same PR.
42+
- Don't add new top-level files unless necessary — prefer extending an existing doc.
43+
- The `datamagic-video` skill has its own conventions; read `datamagic-video/SKILL.md`
44+
before adding or restructuring rules there.
45+
46+
## CI
47+
48+
Every push and PR runs the `docs` workflow ([.github/workflows/docs.yml](./.github/workflows/docs.yml)):
49+
50+
- **markdownlint** — across the whole repo, using `.markdownlint.json`
51+
- **link check** — only the Markdown files changed in the PR, using
52+
`.markdown-link-check.json`
53+
54+
Both jobs run on Node 20 and finish in well under a minute. Please make sure they
55+
pass locally before opening a PR.
56+
57+
## Reporting issues
58+
59+
For product bugs (the hosted app at datamagic.chat), please include a reproducer,
60+
the dataset shape, and the generation mode you used (Full Pipeline / Fast / Single
61+
Chart). For skill / docs issues, link the exact file and line.

‎README.en.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77

88
[![VLDB 2026 Demo](https://img.shields.io/badge/VLDB_2026-Demo_Track-blue)](https://vldb.org/2026/)
99
[![arXiv](https://img.shields.io/badge/arXiv-2606.20388-b31b1b)](https://arxiv.org/abs/2606.20388)
10+
[![docs](https://github.com/HKUSTDial/DataMagic/actions/workflows/docs.yml/badge.svg)](https://github.com/HKUSTDial/DataMagic/actions/workflows/docs.yml)
1011
![Status](https://img.shields.io/badge/status-live-brightgreen)
1112

1213
[中文](./README.md) | [English](./README.en.md)

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77

88
[![VLDB 2026 Demo](https://img.shields.io/badge/VLDB_2026-Demo_Track-blue)](https://vldb.org/2026/)
99
[![arXiv](https://img.shields.io/badge/arXiv-2606.20388-b31b1b)](https://arxiv.org/abs/2606.20388)
10+
[![docs](https://github.com/HKUSTDial/DataMagic/actions/workflows/docs.yml/badge.svg)](https://github.com/HKUSTDial/DataMagic/actions/workflows/docs.yml)
1011
![Status](https://img.shields.io/badge/状态-上线中-brightgreen)
1112

1213
[中文](./README.md) | [English](./README.en.md)

0 commit comments

Comments
 (0)