External link checking + project pages (#2120)

CHANGELOG.md

@@ -20,7 +20,7 @@ Useful links:
 
 ## 0.11.1 or 0.12.0
 
-> ### UNRELEASED: this planned version is still under development
+> **UNRELEASED: this planned version is still under development**
 
 For the full list of changes, see the [0.x.y] release notes.
 
@@ -255,7 +255,8 @@ For the full list of changes, see the [0.7.0] release notes.
 - **Shortcodes**:
   - Now using Hugo's native support for processing HTML & markdown, not file
     extension testing. ([#906])
-  - Dropped support for pre-Hugo-0.54.x behavior of `{{% %}}`. ([#939])
+  - Dropped support for pre-Hugo-0.54.x behavior of [shortcodes with markdown],
+    `{{%/*...*/%}}`. ([#939])
   - `blocks/section`: **default** and accepted values of the `type` argument
     have changed! For details, see [blocks/section] ([#1472]).
   - **Card shortcodes** ([#1376])]:
@@ -268,6 +269,8 @@ For the full list of changes, see the [0.7.0] release notes.
 
 [chroma-docsy]:
   https://www.docsy.dev/docs/adding-content/lookandfeel/#code-highlighting-with-chroma
+[shortcodes with markdown]:
+  https://gohugo.io/content-management/shortcodes/#shortcodes-with-markdown
 
 - **Detection of draw.io diagrams** is now **disabled** by default [#1185]
 
@@ -466,9 +469,10 @@ For the full list of changes, see the [0.2.0] release notes.
 
 <!-- ENTRY TEMPLATE ------------------------------------------------------
 
+```
 ## 0.X.Y
 
-> ### UNRELEASED: this planned version is still under development
+> **UNRELEASED: this planned version is still under development**
 
 For the full list of changes, see the [0.x.y] release notes.
 
@@ -481,5 +485,6 @@ For the full list of changes, see the [0.x.y] release notes.
 **Other changes**:
 
 [0.x.y]: https://github.com/google/docsy/releases/latest?FIXME=v0.X.Y
+```
 
 ---------------------------------------------------------------------------->

CONTRIBUTING.md

@@ -51,9 +51,9 @@ repo.
     the end of the file. (Note that change details are autogenerated by GitHub
     in a later step.)
 3.  **Update Docsy version** to v0.X.Y for:
-    - `version` key in [package.json](package.json)
-    - `version` key in [userguide/hugo.yaml][]
-4.  Run `npm run ci:prepare` to ensure that vendor assets and [go.mod](go.mod)
+    - `version` key in [package.json]
+    - `version` key in [userguide/hugo.yaml]
+4.  Run `npm run ci:prepare` to ensure that vendor assets and [go.mod]
     dependencies are up-to-date.
 5.  **Submit a PR with your changes**, using a title like "Release v0.X.Y
     preparation".
@@ -117,8 +117,8 @@ Assuming that Docsy release v0.X.Y has been successfully deployed and use by at
 least one downstream project, then perform the following actions before any
 further changes are merged into the default branch:
 
-1. Set `version` in [package.json](package.json) to the next planned (or the
-   next dot) release with a dev suffix, such as `v0.X.Z-dev-unreleased`.
+1. Set `version` in [package.json] to the next planned (or the next dot) release
+   with a dev suffix, such as `v0.X.Z-dev-unreleased`.
 2. In the [CHANGELOG]:
    - **Create a new entry** for the next release by copying the ENTRY TEMPLATE
      at the end of the file.
@@ -128,8 +128,11 @@ further changes are merged into the default branch:
    version to next unreleased dev version".
 4. **Get PR approved and merged**.
 
-[CHANGELOG]: CHANGELOG.md
+[CHANGELOG]: https://github.com/google/docsy/blob/main/CHANGELOG.md
 [contribution guidelines]: https://www.docsy.dev/docs/contribution-guidelines/
 [docsy-example]: https://github.com/google/docsy-example
 [Draft a new release]: https://github.com/google/docsy/releases/new
-[userguide/hugo.yaml]: userguide/hugo.yaml
+[go.mod]: https://github.com/google/docsy/blob/main/go.mod
+[package.json]: https://github.com/google/docsy/blob/main/package.json
+[userguide/hugo.yaml]:
+  https://github.com/google/docsy/blob/main/userguide/hugo.yaml

README.md

@@ -6,7 +6,8 @@
 [![Project contributors](https://img.shields.io/github/contributors/google/docsy)](https://github.com/google/docsy/graphs/contributors)
 [![Project license](https://img.shields.io/github/license/google/docsy)](https://github.com/google/docsy/blob/main/LICENSE)
 
-## 🚧 WARNING 🚧 : `main` is under development and potentially unstable! Use official Docsy [releases].
+> **🚧 WARNING 🚧 : `main` is under development and potentially unstable! Use
+> official Docsy [releases].**
 
 Docsy is a [Hugo](https://gohugo.io) theme for technical documentation sets,
 providing simple navigation, site structure, and more.
@@ -95,8 +96,8 @@ requests, see [CONTRIBUTING.md]. Thank you to all past, present, and future
 
 ## License
 
-This project is licensed under the Apache License 2.0 - see the
-[LICENSE.md](https://github.com/google/docsy/blob/main/LICENSE) file for details
+This project is licensed under the Apache License 2.0 - see
+[LICENSE](https://github.com/google/docsy/blob/main/LICENSE) for details
 
 [code of conduct]:
   https://github.com/google/.github/blob/master/CODE_OF_CONDUCT.md

layouts/partials/page-meta-lastmod.html

@@ -2,7 +2,7 @@
 <div class="td-page-meta__lastmod">
   {{ T "post_last_mod" }} {{ .Lastmod.Format .Site.Params.time_format_default -}}
   {{ with .GitInfo }}: {{/* Trim WS */ -}}
-    <a href="{{ $.Site.Params.github_repo }}/commit/{{ .Hash }}">
+    <a data-proofer-ignore href="{{ $.Site.Params.github_repo }}/commit/{{ .Hash }}">
       {{- .Subject }} ({{ .AbbreviatedHash }}) {{- /* Trim WS */ -}}
     </a>
   {{- end }}

package.json

@@ -18,10 +18,9 @@
     "build": "npm run cd:docs build",
     "cd:docs": "npm run _cd:docs -- npm run",
     "check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)",
-    "check:links--md": "echo SKIPPING LINK CHECK 'ls *.md | xargs npx markdown-link-check --config .markdown-link-check.json'",
-    "check:links:all": "npm run cd:docs check:links:all",
+    "check:links:internal": "npm run cd:docs check:links:internal",
     "check:links": "npm run cd:docs check:links",
-    "check": "npm run check:format && npm run check:links--md",
+    "check": "npm run check:format",
     "ci:post": "npm run fix:format && npm run _diff:check",
     "ci:prepare": "npm run docs-install && npm run _prepare && npm run _diff:check",
     "docs-install": "npm run _cd:docs -- npm install",
@@ -42,7 +41,6 @@
   "devDependencies": {
     "cpy-cli": "^5.0.0",
     "hugo-extended": "0.137.0",
-    "markdown-link-check": "^3.13.5",
     "mkdirp": "^3.0.1",
     "prettier": "^3.3.3"
   },
@@ -51,7 +49,7 @@
     "npm-check-updates": "^17.1.10"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "spelling": "cSpell:ignore docsy hugo fortawesome fontawesome onedark twbs netlify pkgs userguide -"
 }

userguide/.htmltest.yml

@@ -2,9 +2,23 @@ DirectoryPath: public
 CheckDoctype: false # Sadly, this is false only because of `static/google*.html`
 IgnoreAltMissing: true # FIXME
 IgnoreDirectoryMissingTrailingSlash: true # FIXME
-IgnoreDirs: [_print] # FIXME
+TestFilesConcurrently: true
+IgnoreDirs:
+  - _print
+  - ^blog/(\d+/)?page/\d+
+  - ^docs/[a-z] # temporary; we'll incrementally add docs sections
 IgnoreEmptyHref: true # FIXME
 IgnoreInternalEmptyHash: true # FIXME
 IgnoreInternalURLs: # list of paths
 IgnoreURLs: # list of regexs of paths or URLs to be ignored
+  - (index.xml|_print/)$ # ignore <link rel=alternate ...>
+  - ^https?://[^/]+/(categories|tags)/ # ignore Docsy-generated content
+  - ^https?://localhost\b
+  # Ignore Docsy-generated GitHub links for now
+  - ^https?://github\.com/.*?/.*?/(new|edit)/ # view-page, edit-source etc
+  # Ignore links to GH repo content for now.
+  - ^https?://github\.com/.*?/.*?/(blob|tree)/
   - ^https://twitter.com/docsydocs$
+  # Too flaky or unnecessary
+  - ^https://badges.netlify.com/api
+  - ^https://code.jquery.com

userguide/.prettierignore

@@ -13,3 +13,5 @@
 /content/en/docs/adding-content/*
 
 !/content/en/docs/adding-content/lookandfeel.md
+
+!/static

userguide/Makefile

@@ -1,6 +1,11 @@
+# Set REFCACHE to another value to disable htmltest refcache-file manipulation
+REFCACHE?=refcache
 HTMLTEST_DIR=tmp
 HTMLTEST?=htmltest # Specify as make arg if different
-HTMLTEST_ARGS?=--skip-external
+HTMLTEST_ARGS?=--log-level 1
+LINK_CACHE_FILE?=refcache.json
+LINK_CACHE_FILE_DEST_DIR?=static
+LINK_CACHE_FILE_SRC_DIR?=$(HTMLTEST_DIR)/.htmltest
 
 # Use $(HTMLTEST) in PATH, if available; otherwise, we'll get a copy
 ifeq (, $(shell which $(HTMLTEST)))
@@ -10,7 +15,36 @@ GET_LINK_CHECKER_IF_NEEDED=get-link-checker
 endif
 endif
 
-check-links: $(GET_LINK_CHECKER_IF_NEEDED)
+default:
+	@echo "Make what? Target list:\n"
+	@make -rpn | grep '^[a-z]\S*:' | sed 's/://' | sort
+
+$(LINK_CACHE_FILE_SRC_DIR):
+	mkdir -p $(LINK_CACHE_FILE_SRC_DIR)
+
+$(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE):
+	mkdir -p $(LINK_CACHE_FILE_DEST_DIR)
+	echo '{}' > $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE)
+
+refcache-restore: $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE) $(LINK_CACHE_FILE_SRC_DIR)
+ifeq (refcache, $(REFCACHE))
+	cp $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE) $(LINK_CACHE_FILE_SRC_DIR)/
+else
+	@echo "SKIPPING refcache-restore"
+endif
+
+refcache-save:
+ifeq (refcache, $(REFCACHE))
+	cp $(LINK_CACHE_FILE_SRC_DIR)/$(LINK_CACHE_FILE) $(LINK_CACHE_FILE_DEST_DIR)/
+	npx prettier --prose-wrap=always --write $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE)
+else
+	@echo "SKIPPING refcache-save"
+endif
+
+check-links: $(GET_LINK_CHECKER_IF_NEEDED) \
+	refcache-restore check-links-only refcache-save
+
+check-links-only:
 	$(HTMLTEST) $(HTMLTEST_ARGS)
 
 clean:

userguide/content/en/project/_index.md

@@ -0,0 +1,16 @@
+---
+title: Docsy project
+linkTitle: Project
+description: Docsy project design documentation and other resources
+outputs: [HTML]
+cascade:
+  type: docs
+  # ui:
+  #   breadcrumb_disable: true
+---
+
+- Docsy build and design notes (TBC)
+- Repository files:
+  - [CHANGELOG](changelog)
+  - [CONTRIBUTING](contributing)
+  - [README](readme)

userguide/hugo.yaml

@@ -104,6 +104,10 @@ params:
         icon: fa-brands fa-stack-overflow
         desc: Practical questions and curated answers
     developer:
+      - name: Project info
+        url: /project/
+        icon: fa fa-book
+        desc: Project design documentation and resources
       - name: GitHub
         url: https://github.com/google/docsy
         icon: fa-brands fa-github
@@ -129,3 +133,10 @@ module:
   mounts:
     - source: content/en
       target: content
+    # Mount the repo's top-level .md files under project
+    - source: ../README.md
+      target: content/project/readme.md
+    - source: ../CHANGELOG.md
+      target: content/project/changelog.md
+    - source: ../CONTRIBUTING.md
+      target: content/project/contributing.md

userguide/package.json

@@ -2,24 +2,25 @@
   "name": "docsy-user-guide",
   "scripts": {
     "_build": "npm run _hugo-dev --",
-    "_check:format": "npx prettier --check .",
-    "_check:links": "make check-links",
-    "_hugo": "hugo --cleanDestinationDir --themesDir ../..",
+    "_check:format": "npx prettier --prose-wrap=always --check .",
+    "_check:links--warn": "npm run _check:links || (echo; echo 'WARNING: see link-checker output for issues.'; echo)",
+    "_check:links": "make --keep-going check-links",
     "_hugo-dev": "npm run _hugo -- -e dev -DFE",
+    "_hugo": "hugo --cleanDestinationDir --themesDir ../..",
     "_serve": "npm run _hugo-dev -- serve --minify --disableFastRender --renderToMemory",
     "build:preview": "npm run _hugo-dev -- --minify --baseURL \"${DEPLOY_PRIME_URL:-http://localhost}\"",
     "build:production": "npm run _hugo -- --minify",
     "build": "npm run _build --",
     "check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)",
-    "check:links:all": "HTMLTEST_ARGS= npm run _check:links",
+    "check:links:internal": "HTMLTEST_ARGS='--skip-external' npm run _check:links",
     "check:links": "npm run _check:links",
     "clean": "rm -Rf public",
     "fix:format": "npm run _check:format -- --write",
     "make:public": "git init -b main public",
+    "postbuild:preview": "npm run _check:links--warn",
+    "postbuild:production": "npm run _check:links--warn",
     "precheck:links:all": "npm run build",
     "precheck:links": "npm run build",
-    "postbuild:preview": "npm run _check:links",
-    "postbuild:production": "npm run _check:links",
     "prepare": "cd .. && npm install",
     "serve": "npm run _serve",
     "test": "npm run check:format && npm run check:links",
@@ -30,5 +31,6 @@
     "autoprefixer": "^10.4.20",
     "postcss-cli": "^11.0.0",
     "rtlcss": "^4.3.0"
-  }
+  },
+  "cSpell:ignore": "- docsy htmltest pkgs postbuild precheck rtlcss -"
 }