Add docs CI + CONTRIBUTING + gitignore

.github/workflows/docs.yml

@@ -0,0 +1,90 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "**/*.md"
+      - ".github/workflows/docs.yml"
+      - ".markdownlint.json"
+      - ".markdown-link-check.json"
+  pull_request:
+    paths:
+      - "**/*.md"
+      - ".github/workflows/docs.yml"
+      - ".markdownlint.json"
+      - ".markdown-link-check.json"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  markdownlint:
+    name: markdownlint
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install markdownlint-cli
+        run: npm install -g markdownlint-cli@0.41.0
+
+      - name: Run markdownlint
+        run: markdownlint "**/*.md" --ignore node_modules
+
+  link-check:
+    name: link check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Collect changed Markdown files
+        id: changed
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          BEFORE_SHA: ${{ github.event.before }}
+          AFTER_SHA: ${{ github.sha }}
+        run: |
+          set -euo pipefail
+          if [ "$EVENT_NAME" = "pull_request" ]; then
+            files=$(git diff --name-only --diff-filter=AM "$BASE_SHA" "$HEAD_SHA" -- '*.md')
+          elif [ "$EVENT_NAME" = "push" ] && [ -n "${BEFORE_SHA:-}" ] && [ "$BEFORE_SHA" != "0000000000000000000000000000000000000000" ]; then
+            files=$(git diff --name-only --diff-filter=AM "$BEFORE_SHA" "$AFTER_SHA" -- '*.md')
+          else
+            files=""
+          fi
+          {
+            echo "files<<EOF"
+            echo "$files"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Install markdown-link-check
+        if: steps.changed.outputs.files != ''
+        run: npm install -g markdown-link-check@3.12.2
+
+      - name: Run markdown-link-check
+        if: steps.changed.outputs.files != ''
+        env:
+          FILES: ${{ steps.changed.outputs.files }}
+        run: |
+          set -uo pipefail
+          fail=0
+          while IFS= read -r f; do
+            [ -z "$f" ] && continue
+            [ -f "$f" ] || continue
+            echo "::group::$f"
+            markdown-link-check -q -c .markdown-link-check.json "$f" || fail=1
+            echo "::endgroup::"
+          done <<< "$FILES"
+          exit $fail

.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+.DS_Store
+*.log

.markdown-link-check.json

@@ -0,0 +1,14 @@
+{
+  "timeout": "10s",
+  "retryOn429": true,
+  "retryCount": 3,
+  "fallbackRetryDelay": "30s",
+  "aliveStatusCodes": [200, 206, 301, 302, 303, 307, 308],
+  "ignorePatterns": [
+    { "pattern": "^https://github.com/user-attachments/assets" },
+    { "pattern": "^https://arxiv.org/" },
+    { "pattern": "^http://localhost" },
+    { "pattern": "^#.*" },
+    { "pattern": "^\\./images/demo-hero\\.gif$" }
+  ]
+}

.markdownlint.json

@@ -0,0 +1,16 @@
+{
+  "default": true,
+  "MD012": false,
+  "MD013": false,
+  "MD022": false,
+  "MD024": { "siblings_only": true },
+  "MD026": false,
+  "MD028": false,
+  "MD031": false,
+  "MD032": false,
+  "MD033": false,
+  "MD034": false,
+  "MD036": false,
+  "MD040": false,
+  "MD041": false
+}

CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to DataMagic
+
+Thanks for your interest in DataMagic. The repo is currently **docs-first** —
+the production product lives at [datamagic.chat](https://datamagic.chat/), while this
+repository holds the public documentation, the published paper artifacts, and the
+[`datamagic-video`](./datamagic-video/) skill for AI coding agents.
+
+So contributions today land in one of four buckets:
+
+| Bucket | Examples |
+|---|---|
+| Docs (Chinese / English) | typo fixes, clearer explanations, broken links, missing context |
+| The `datamagic-video` skill | new rule pages, refining narrative patterns, chart-selection guidance, anti-patterns |
+| Examples | new input/output examples under `docs/input-output-examples*.md` |
+| Infrastructure | CI, link checking, lint config |
+
+Please open an Issue first for anything beyond a small fix so we can align on scope.
+
+## Quick start
+
+```bash
+git clone https://github.com/HKUSTDial/DataMagic
+cd DataMagic
+```
+
+The repo has no build step. To preview your edits, just open the Markdown files
+locally (or in your editor's preview pane). To match what CI checks, run:
+
+```bash
+# Markdown lint (matches the rules in .markdownlint.json)
+npx --yes markdownlint-cli@0.41.0 "**/*.md" --ignore node_modules
+
+# Link check on a single file
+npx --yes markdown-link-check@3.12.2 -c .markdown-link-check.json README.md
+```
+
+## Style
+
+- Keep both `README.md` (中文) and `README.en.md` (English) in sync when editing
+  shared sections (links, badges, examples, roadmap).
+- For per-doc Chinese / English pairs under `docs/`, edit both files in the same PR.
+- Don't add new top-level files unless necessary — prefer extending an existing doc.
+- The `datamagic-video` skill has its own conventions; read `datamagic-video/SKILL.md`
+  before adding or restructuring rules there.
+
+## CI
+
+Every push and PR runs the `docs` workflow ([.github/workflows/docs.yml](./.github/workflows/docs.yml)):
+
+- **markdownlint** — across the whole repo, using `.markdownlint.json`
+- **link check** — only the Markdown files changed in the PR, using
+  `.markdown-link-check.json`
+
+Both jobs run on Node 20 and finish in well under a minute. Please make sure they
+pass locally before opening a PR.
+
+## Reporting issues
+
+For product bugs (the hosted app at datamagic.chat), please include a reproducer,
+the dataset shape, and the generation mode you used (Full Pipeline / Fast / Single
+Chart). For skill / docs issues, link the exact file and line.

README.en.md

@@ -7,6 +7,7 @@
 
 [![VLDB 2026 Demo](https://img.shields.io/badge/VLDB_2026-Demo_Track-blue)](https://vldb.org/2026/)
 [![arXiv](https://img.shields.io/badge/arXiv-2606.20388-b31b1b)](https://arxiv.org/abs/2606.20388)
+[![docs](https://github.com/HKUSTDial/DataMagic/actions/workflows/docs.yml/badge.svg)](https://github.com/HKUSTDial/DataMagic/actions/workflows/docs.yml)
 ![Status](https://img.shields.io/badge/status-live-brightgreen)
 
 [中文](./README.md) | [English](./README.en.md)

README.md

@@ -7,6 +7,7 @@
 
 [![VLDB 2026 Demo](https://img.shields.io/badge/VLDB_2026-Demo_Track-blue)](https://vldb.org/2026/)
 [![arXiv](https://img.shields.io/badge/arXiv-2606.20388-b31b1b)](https://arxiv.org/abs/2606.20388)
+[![docs](https://github.com/HKUSTDial/DataMagic/actions/workflows/docs.yml/badge.svg)](https://github.com/HKUSTDial/DataMagic/actions/workflows/docs.yml)
 ![Status](https://img.shields.io/badge/状态-上线中-brightgreen)
 
 [中文](./README.md) | [English](./README.en.md)