diff --git a/README.md b/README.md index cd5031b..ed38a74 100644 --- a/README.md +++ b/README.md @@ -3,14 +3,14 @@ This site contains resources provided by the CNCF Technical Documentation team, including: -- [Docs](docs) about building websites and developing technical documentation, +- [Docs](docs/) about building websites and developing technical documentation, including recommended tools, best practices, how-tos, and evaluation checklists. It provides specific guidelines for: - Setting up and maintaining a documentation website. - Writing technical documentation for a project. - Seeking assistance from the CNCF TechDocs community. - [Analyzing project documentation](docs/analysis/). -- [Analyses](analyses): a collection of documentation analyses of CNCF projects +- [Analyses](analyses/): a collection of documentation analyses of CNCF projects performed by the TechDocs team. ## TechDocs Q&A diff --git a/package.json b/package.json index b9170fe..685fd9d 100644 --- a/package.json +++ b/package.json @@ -3,44 +3,46 @@ "version": "0.0.0", "description": "Resources provided by the CNCF Technical Documentation team.", "scripts": { - "_build": "docusaurus build", + "_build": "npm run docus:build", "_check:format:any": "npx prettier --check --ignore-path ''", "_check:format:delta": "npm run _check:format:any -- $(npm run -s _list:git:delta)", "_check:format": "npx prettier --check .", "_check:links-md": "bash -c 'for f in *.md `find analyses -name \"*.md\"`; do npx markdown-link-check --config .markdown-link-check.json -p -v $f || exit 1; done'", "_check:links:internal": "npm run _check:links -- HTMLTEST_ARGS='--skip-external'", "_check:links": "make --keep-going check-links", + "_check:markdown:1": "npx -p markdownlint-cli markdownlint -c .markdownlint.yaml", "_check:markdown:all": "npm run -s _list:check:md | xargs -I {} -P 4 npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}", "_check:markdown:delta": "npm run -s _list:git:delta | xargs -I {} npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}", - "_check:markdown:1": "npx -p markdownlint-cli markdownlint -c .markdownlint.yaml", - "_list:git:delta": "git diff --name-only --diff-filter=ACMR | grep -E '\\.(js|md|scss|yml|yaml)$'", + "_list:check:*": "npm run --loglevel=warn | grep -Ee '^\\s*check:[^:]+$'", "_list:check:md:no-analysis": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' -a -not -path '*/00*'", "_list:check:md": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' | grep -Eve '/000|/0010'", - "_list:check:*": "npm run --loglevel=warn | grep -Ee '^\\s*check:[^:]+$'", "_list:fix:*": "npm run --loglevel=warn | grep -Ee '^\\s*fix:[^:]+$' | grep -v 'fix:all'", + "_list:git:delta": "git diff --name-only --diff-filter=ACMR | grep -E '\\.(js|md|scss|yml|yaml)$'", + "build:preview": "npm run _build", + "build:production": "npm run _build", + "build": "BUILD_ENV=dev npm run _build", "check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)", "check:links": "npm run _check:links", "check:markdown": "npm run _check:markdown:all", "check:spelling": "npx cspell --no-progress -c .cspell.yml analyses docs *.md", "check": "npm run seq -- $(npm run -s _list:check:*)", + "docus:build": "docusaurus build", + "docus:clear": "docusaurus clear", + "docus:deploy": "docusaurus deploy", + "docus:serve": "docusaurus serve", + "docus:start": "docusaurus start", + "docus:swizzle": "docusaurus swizzle", + "docus:write-heading-ids": "docusaurus write-heading-ids", + "docus:write-translations": "docusaurus write-translations", + "docusaurus": "docusaurus", "fix:format": "npm run _check:format -- --write", "fix": "npm run seq -- $(npm -s run _list:fix:*)", "precheck:links": "npm run build", "seq": "bash -c 'for cmd in \"$@\"; do npm run $cmd || exit 1; done' - ", + "serve": "npm run docus:serve", "test": "npm run check", - "update:pkgs": "npx npm-check-updates -u", - "docusaurus": "docusaurus", - "start": "docusaurus start", - "build:preview": "npm run _build", - "build:production": "npm run _build", - "build": "BUILD_ENV=dev npm run _build", - "swizzle": "docusaurus swizzle", - "deploy": "docusaurus deploy", - "clear": "docusaurus clear", - "serve": "docusaurus serve", - "write-translations": "docusaurus write-translations", - "write-heading-ids": "docusaurus write-heading-ids", - "typecheck": "tsc" + "typecheck": "tsc", + "update:pkgs": "npx npm-check-updates -u" }, "author": "CNCF", "license": "CC-BY-4.0", @@ -50,23 +52,23 @@ "@mdx-js/react": "^3.1.0", "clsx": "^2.1.1", "prism-react-renderer": "^2.4.1", - "react": "^19.1.0", - "react-dom": "^19.1.0" + "react-dom": "^19.1.0", + "react": "^19.1.0" }, "devDependencies": { - "cspell": "^9.1.1", - "markdown-link-check": "3.13.7", - "markdownlint": "^0.38.0", - "markdownlint-cli": "^0.45.0", - "npm-check-updates": "^18.0.1", - "prettier": "^3.5.3", "@docusaurus/module-type-aliases": "3.8.1", "@docusaurus/tsconfig": "3.8.1", "@docusaurus/types": "3.8.1", + "cspell": "^9.1.1", + "markdown-link-check": "3.13.7", + "markdownlint-cli": "^0.45.0", + "markdownlint": "^0.38.0", + "npm-check-updates": "^18.0.1", + "prettier": "^3.5.3", "typescript": "~5.8.3" }, "private": true, - "spelling": "cSpell:ignore ACMR HTMLTEST loglevel pkgs -", + "spelling": "cSpell:ignore ACMR docus HTMLTEST loglevel pkgs -", "prettier": { "proseWrap": "always", "singleQuote": true