docs: reorganize the documentation around reader intent

website/.vitepress/components/GuideRedirect.vue

@@ -0,0 +1,30 @@
+<script setup lang="ts">
+import { onMounted, onUnmounted } from 'vue';
+import { guideAnchors } from '../guideAnchors';
+
+// The guide used to be a single page, so links to it in issues, blog posts and
+// Stack Overflow answers point at anchors that now live on other pages. Netlify
+// never receives the fragment, so this has to be resolved in the browser.
+//
+// location.replace rather than the VitePress router: the router leaves the new
+// fragment unscrolled, and it pushes a history entry, so going back would land
+// on the guide with the old hash still set and redirect again.
+function resolve() {
+  const hash = window.location.hash.slice(1);
+  if (!hash) return;
+
+  const target = guideAnchors[decodeURIComponent(hash).toLowerCase()];
+  if (target) window.location.replace(target);
+}
+
+onMounted(() => {
+  resolve();
+  window.addEventListener('hashchange', resolve);
+});
+
+onUnmounted(() => window.removeEventListener('hashchange', resolve));
+</script>
+
+<template>
+  <span hidden />
+</template>

website/.vitepress/config.ts

@@ -144,6 +144,23 @@ export default defineConfig({
     ).href;
     head.push(['link', { rel: 'canonical', href: canonicalUrl }]);
 
+    // The DocSearch crawler otherwise has to infer a record's section from the
+    // active sidebar link in the DOM. Stating it on the page is steadier: it
+    // survives a theme upgrade, and it is what hierarchy.lvl0 - the breadcrumb
+    // on every search result - should be set from.
+    if (pageData.frontmatter.section) {
+      head.push([
+        'meta',
+        { name: 'docsearch:section', content: pageData.frontmatter.section }
+      ])
+    }
+    if (pageData.frontmatter.docType) {
+      head.push([
+        'meta',
+        { name: 'docsearch:doc_type', content: pageData.frontmatter.docType }
+      ])
+    }
+
     // Dynamic Open Graph and Twitter meta tags
     const isHome = new URL(canonicalUrl).pathname === '/';
     let pageTitle = pageData.frontmatter.title || pageData.title || taskName;
@@ -297,6 +314,11 @@ export default defineConfig({
   srcDir: 'src',
   cleanUrls: true,
   srcExclude: [`${other}/**`, `${channel}/docs/**/template.md`],
+  // A function rather than the equivalent `{ '<channel>/:path*': ':path*' }`.
+  // vitepress-plugin-llms reuses this config to name its Markdown output, and
+  // on the object form it compiles the `:path*` array parameter back without
+  // separators, producing dist/docsreferencecli.md instead of
+  // dist/docs/reference/cli.md and breaking every relative link in them.
   rewrites: (id) =>
     id.startsWith(`${channel}/`) ? id.slice(channel.length + 1) : id,
   markdown: {
@@ -381,7 +403,9 @@ export default defineConfig({
       { text: 'Home', link: '/' },
       {
         text: 'Docs',
-        link: '/docs/guide',
+        // The landing page only exists on next until cmd/release promotes it;
+        // the released channel still has to enter the section at the guide.
+        link: isLatest ? '/docs/guide' : '/docs/',
         activeMatch: '^/docs'
       },
       { text: 'Blog', link: '/blog', activeMatch: '^/blog' },

website/.vitepress/guideAnchors.ts

@@ -0,0 +1,104 @@
+// Where each section of the old single-page guide went when it was
+// split up. Netlify never sees the URL fragment, so a _redirects rule
+// cannot route these; GuideRedirect.vue resolves them in the browser.
+export const guideAnchors: Record<string, string> = {
+  'running-taskfiles': '/docs/guide/running-tasks',
+  'supported-file-names': '/docs/guide/running-tasks#supported-file-names',
+  'running-a-taskfile-from-a-subdirectory':
+    '/docs/guide/running-tasks#running-a-taskfile-from-a-subdirectory',
+  'running-a-global-taskfile':
+    '/docs/guide/running-tasks#running-a-global-taskfile',
+  'running-a-taskfile-from-stdin':
+    '/docs/guide/running-tasks#running-a-taskfile-from-stdin',
+  'running-a-remote-taskfile':
+    '/docs/remote-taskfiles#specifying-a-remote-entrypoint',
+  'environment-variables': '/docs/guide/environment',
+  task: '/docs/guide/environment#task',
+  'env-files': '/docs/guide/environment#env-files',
+  'including-other-taskfiles': '/docs/guide/includes',
+  'remote-taskfiles': '/docs/guide/includes#remote-taskfiles',
+  'os-specific-taskfiles': '/docs/guide/includes#os-specific-taskfiles',
+  'directory-of-included-taskfile':
+    '/docs/guide/includes#directory-of-included-taskfile',
+  'optional-includes': '/docs/guide/includes#optional-includes',
+  'internal-includes': '/docs/guide/includes#internal-includes',
+  'flatten-includes': '/docs/guide/includes#flatten-includes',
+  'exclude-tasks-from-being-included':
+    '/docs/guide/includes#exclude-tasks-from-being-included',
+  'vars-of-included-taskfiles':
+    '/docs/guide/includes#vars-of-included-taskfiles',
+  'namespace-aliases': '/docs/guide/includes#namespace-aliases',
+  'internal-tasks': '/docs/guide/defining-tasks#internal-tasks',
+  'task-directory': '/docs/guide/defining-tasks#task-directory',
+  'task-dependencies': '/docs/guide/dependencies#task-dependencies',
+  'fail-fast-dependencies': '/docs/guide/dependencies#fail-fast-dependencies',
+  'platform-specific-tasks-and-commands':
+    '/docs/guide/platforms#platform-specific-tasks-and-commands',
+  'calling-another-task': '/docs/guide/dependencies#calling-another-task',
+  'prevent-unnecessary-work': '/docs/guide/up-to-date',
+  'by-fingerprinting-locally-generated-files-and-their-sources':
+    '/docs/guide/up-to-date#by-fingerprinting-locally-generated-files-and-their-sources',
+  'using-programmatic-checks-to-indicate-a-task-is-up-to-date':
+    '/docs/guide/up-to-date#using-programmatic-checks-to-indicate-a-task-is-up-to-date',
+  'using-programmatic-checks-to-cancel-the-execution-of-a-task-and-its-dependencies':
+    '/docs/guide/conditional-execution#using-programmatic-checks-to-cancel-the-execution-of-a-task-and-its-dependencies',
+  'conditional-execution-with-if':
+    '/docs/guide/conditional-execution#conditional-execution-with-if',
+  'task-level-if': '/docs/guide/conditional-execution#task-level-if',
+  'command-level-if': '/docs/guide/conditional-execution#command-level-if',
+  'using-templates-in-if-conditions':
+    '/docs/guide/conditional-execution#using-templates-in-if-conditions',
+  'using-if-with-for-loops':
+    '/docs/guide/conditional-execution#using-if-with-for-loops',
+  'if-vs-preconditions':
+    '/docs/guide/conditional-execution#if-vs-preconditions',
+  'limiting-when-tasks-run':
+    '/docs/guide/conditional-execution#limiting-when-tasks-run',
+  'ensuring-required-variables-are-set':
+    '/docs/guide/required-variables#ensuring-required-variables-are-set',
+  'ensuring-required-variables-have-allowed-values':
+    '/docs/guide/required-variables#ensuring-required-variables-have-allowed-values',
+  'using-variable-references-for-enum-values':
+    '/docs/guide/required-variables#using-variable-references-for-enum-values',
+  'prompting-for-missing-variables-interactively':
+    '/docs/guide/required-variables#prompting-for-missing-variables-interactively',
+  variables: '/docs/guide/variables',
+  'dynamic-variables': '/docs/guide/variables#dynamic-variables',
+  'referencing-other-variables':
+    '/docs/guide/variables#referencing-other-variables',
+  'parsing-json-yaml-into-map-variables':
+    '/docs/guide/variables#parsing-json-yaml-into-map-variables',
+  'secret-variables': '/docs/guide/variables#secret-variables',
+  'looping-over-values': '/docs/guide/loops',
+  'looping-over-a-static-list': '/docs/guide/loops#looping-over-a-static-list',
+  'looping-over-a-matrix': '/docs/guide/loops#looping-over-a-matrix',
+  'looping-over-your-task-s-sources-or-generated-files':
+    '/docs/guide/loops#looping-over-your-task-s-sources-or-generated-files',
+  'looping-over-variables': '/docs/guide/loops#looping-over-variables',
+  'renaming-variables': '/docs/guide/loops#renaming-variables',
+  'looping-over-tasks': '/docs/guide/loops#looping-over-tasks',
+  'looping-over-dependencies': '/docs/guide/loops#looping-over-dependencies',
+  'forwarding-cli-arguments-to-commands':
+    '/docs/guide/arguments#forwarding-cli-arguments-to-commands',
+  'wildcard-arguments': '/docs/guide/arguments#wildcard-arguments',
+  'doing-task-cleanup-with-defer':
+    '/docs/guide/dependencies#doing-task-cleanup-with-defer',
+  help: '/docs/guide/defining-tasks#help',
+  'display-summary-of-task':
+    '/docs/guide/defining-tasks#display-summary-of-task',
+  'task-aliases': '/docs/guide/defining-tasks#task-aliases',
+  'overriding-task-name': '/docs/guide/defining-tasks#overriding-task-name',
+  'warning-prompts': '/docs/guide/required-variables#warning-prompts',
+  'silent-mode': '/docs/guide/output#silent-mode',
+  'dry-run-mode': '/docs/guide/running-tasks#dry-run-mode',
+  'ignore-errors': '/docs/guide/output#ignore-errors',
+  'output-syntax': '/docs/guide/output#output-syntax',
+  'ci-integration': '/docs/guide/output#ci-integration',
+  'colored-output': '/docs/guide/output#colored-output',
+  'error-annotations': '/docs/guide/output#error-annotations',
+  'interactive-cli-application':
+    '/docs/guide/running-tasks#interactive-cli-application',
+  'short-task-syntax': '/docs/guide/defining-tasks#short-task-syntax',
+  'set-and-shopt': '/docs/guide/platforms#set-and-shopt',
+  'watch-tasks': '/docs/guide/watch'
+};