Merge branch 'upstream/docs-tooling-followup' into docs/tooling-and-filecoin-pin-restore

Author: nijoe1

.github/workflows/check-external-links.yml

@@ -1,8 +1,7 @@
 name: Check external links
 
 on:
-  pull_request:
-    branches: [ main, staging, production ]
+  push:
 
 jobs:
   linkChecker:

.github/workflows/docs-quality.yml

@@ -0,0 +1,59 @@
+name: Documentation Quality
+
+on:
+  push:
+
+jobs:
+  lint:
+    name: Markdown Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run markdown linter
+        run: npm run lint:summary
+
+  internal-links:
+    name: Internal Links
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Check internal links
+        run: npm run check-links
+
+  redirects:
+    name: Redirects Validation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Validate redirects
+        run: npm run check:redirects

.gitignore

@@ -14,4 +14,7 @@ _book/
 _book_temp/
 node_modules/
 package-lock.json
-.gitbook/cli/
+.gitbook/cli/
+.mcp.json
+.claude/
+scripts/checkers/dist/

.lycheeignore

@@ -1,3 +1,23 @@
 # Filfox.info blocks automated requests (returns 500/503)
 # but links work fine in browsers
 https://filfox.info
+
+# Bacalhau sites currently fail intermittently from CI runners.
+# Keep links in docs, but don't fail PR CI on transient network errors.
+https://docs.bacalhau.org
+https://www.bacalhau.org
+
+# Airtable feedback links intermittently return 502 from CI runners.
+https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form
+
+# Known flaky or stale external endpoints referenced in historical docs.
+https://singularity.storage
+https://calc.filecoin.eu
+https://thegraph.academy
+https://docs.0x.org/introduction/introduction-to-0x
+
+# eOracle GitBook URL currently returns 404 from CI; keep temporary ignore.
+https://eoracle.gitbook.io/eoracle/price-feeds/integration-guide
+
+# WeChat mobile page intermittently times out from CI runners.
+https://www.wechat.com/mobile

.markdownlint-cli2.jsonc

@@ -0,0 +1,52 @@
+{
+  "config": {
+    "default": true,
+    "MD004": { "style": "asterisk" },
+    "MD013": false,
+    "MD029": false,
+    "MD036": false,
+    "MD024": { "siblings_only": true },
+    "MD033": {
+      "allowed_elements": [
+        "a",
+        "b",
+        "br",
+        "code",
+        "details",
+        "div",
+        "em",
+        "figcaption",
+        "figure",
+        "img",
+        "li",
+        "mark",
+        "meta",
+        "ol",
+        "p",
+        "pre",
+        "span",
+        "strong",
+        "sub",
+        "summary",
+        "sup",
+        "table",
+        "tbody",
+        "td",
+        "th",
+        "thead",
+        "tr",
+        "ul"
+      ]
+    }
+  },
+  "ignores": [
+    "_book/**",
+    "node_modules/**",
+    ".claude/**",
+    ".cursor/**",
+    ".zed/**",
+    ".agents/**",
+    ".gitbook/**",
+    "reference/json-rpc/**"
+  ]
+}

.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+  "recommendations": [
+    "DavidAnson.vscode-markdownlint"
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+  "files.trimTrailingWhitespace": true,
+  "files.insertFinalNewline": true,
+  "files.trimFinalNewlines": true,
+  "[markdown]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "DavidAnson.vscode-markdownlint",
+    "editor.codeActionsOnSave": {
+      "source.fixAll.markdownlint": "explicit"
+    }
+  },
+  "markdownlint.run": "onType",
+  "typescript.tsdk": "node_modules/typescript/lib"
+}

README.md

@@ -1,5 +1,7 @@
+# Filecoin Docs
+
 <div align=center>
-    
+
 [![MIT License](https://img.shields.io/badge/license-MIT-blueviolet?style=for-the-badge)](https://protocol.ai/blog/announcing-the-permissive-license-stack/)
 [![Website status](https://img.shields.io/website.svg?style=for-the-badge&url=https%3A%2F%2Fdocs.filecoin.io)](https://docs.filecoin.io/)
 [![Backlog](https://img.shields.io/badge/backlog-Updated-blue?style=for-the-badge)](https://github.com/orgs/filecoin-project/projects/103/views/1)
@@ -9,20 +11,21 @@
 
 ## Table of contents <!-- omit in toc -->
 
-- [About this repo](#about-this-repo)
-- [Contributing](#contributing)
-  - [Local Development](#local-development)
-  - [Link checking](#link-checking)
-- [Issues](#issues)
-  - [Backlog](#backlog)
-  - [Priority](#priority)
-- [License](#license)
+* [About this repo](#about-this-repo)
+* [Contributing](#contributing)
+  * [Local Development](#local-development)
+  * [Link checking](#link-checking)
+* [Issues](#issues)
+  * [Backlog](#backlog)
+  * [Priority](#priority)
+* [License](#license)
 
 ## About this repo
 
 This repository manages the documentation for the [Filecoin network](https://filecoin.io). The content is built and hosted by [GitBook](https://gitbook.com). View the docs site at [docs.filecoin.io](https://docs.filecoin.io).
 
 ## Publishing
+
 This repo is synced to [GitBook](https://gitbook.com) using [GitBook's GitSync](https://gitbook.com/docs/getting-started/git-sync).  When a PR to `main` is merged, a new GitBook is published.  This happens as a result of the GitBook applicaiton, not a GitHub Action workflow in the repo.  
 
 PRs also generate preview links so one can preview the site before merging.  Per [GitBook GitSync integration](https://app.gitbook.com/o/NNmD4UvLc26b1TmEYgzE/s/xNWFG7bQkjLkl5BBGjbD/~/integrations/github), preview links from fork PRs have been enabled.  
@@ -46,6 +49,7 @@ You can build and preview the documentation locally.
    ```
 
 2. **Develop**: Builds and serves the site with live reload.
+
    ```bash
    npm run serve
    ```
@@ -58,17 +62,15 @@ You can build and preview the documentation locally.
 | `npm run build`   | Builds the static site to the `_book/` directory                                                      |
 | `npm run preview` | Serves the existing `_book/` directory without rebuilding                                             |
 
-
 ### Link checking
 
 Links are checked using [lychee-action](https://github.com/lycheeverse/lychee-action) as configured by [check-external-links.yml](.github/workflows/check-external-links.yml).  Working links are required before merging.  If you have a link that should be excluded from checking:
+
 1. wrap it in `` `backticks` `` OR
 2. wrap it in `<code>` blocks OR
-3. use [`.lycheeignore`](https://github.com/lycheeverse/lychee-action?tab=readme-ov-file#excluding-links-from-getting-checked) 
-
-
+3. use [`.lycheeignore`](https://github.com/lycheeverse/lychee-action?tab=readme-ov-file#excluding-links-from-getting-checked)
 
-## Issues 
+## Issues
 
 Found a problem with the Filecoin docs site? [Please raise an issue](https://github.com/filecoin-project/filecoin-docs/issues/new). Be as specific and descriptive as possible; screenshots help!
 

WELCOME.md

@@ -21,8 +21,6 @@ layout:
     visible: true
 ---
 
-# Welcome to Filecoin Docs
-
 Choose your own path to start exploring Filecoin:
 
 <table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>💡 <strong>Learn the basics</strong></td><td>New to Filecoin and looking for foundational concepts? Start with the Basics section to understand the essentials and kick off your journey!</td><td></td><td><a href="getting-started/what-is-filecoin/">what-is-filecoin</a></td></tr><tr><td>🔧 <strong>Build with Filecoin</strong></td><td>Ready to develop on the Filecoin network? Head to the Developers section for guides and examples to help bring your project to life.</td><td></td><td><a href="core-concepts/filecoin-virtual-machine/">the-fvm.md</a></td></tr><tr><td>🏗️ <strong>Become a Storage Provider</strong></td><td>Thinking about running a provider node on Filecoin? Visit the Provider section for comprehensive guidance on getting started.</td><td></td><td><a href="storage-providers/getting-started.md">getting-started.md</a></td></tr><tr><td>📊 <strong>Store data</strong></td><td>Looking to store large volumes of data? Explore the Store section to review the various storage options Filecoin offers.</td><td></td><td><a href="getting-started/what-is-filecoin/storage-model.md">storage-model.md</a></td></tr></tbody></table>

book.json

@@ -2,5 +2,5 @@
   "structure": {
     "readme": "WELCOME.md"
   },
-  "plugins": ["filecoin", "-highlight"]
+  "plugins": ["filecoin", "-highlight", "-search", "-lunr"]
 }