Add agent-friendly support plan and phase 1 implementation of Markdown output

.vscode/cspell.json

@@ -31,10 +31,12 @@
     "markdownify",
     "mentees",
     "navbars",
+    "nguyen",
     "nvmrc",
     "Occitan",
     "pageinfo",
     "pexels",
+    "quang",
     "refcache",
     "relref",
     "scrollspy",
@@ -46,6 +48,8 @@
     "unselectable",
     "upvote",
     "viewports",
+    "vinh",
+    "vsoch",
     "warnf",
     "warnidf",
     "wrapup"

docsy.dev/.prettierignore

@@ -16,3 +16,5 @@
 !/content/fr/**/*.*
 
 /layouts
+
+/tests/md-output/goldens/**/*.*

docsy.dev/config/_default/hugo.yaml

@@ -12,9 +12,9 @@ ignoreLogs:
   - warning-frontmatter-params-overrides # cSpell:disable-line
 
 outputs:
-  home: [HTML]
-  page: [HTML]
-  section: [HTML, RSS, print]
+  home: [HTML, Markdown]
+  page: [HTML, Markdown]
+  section: [HTML, RSS, print, Markdown]
 
 imaging:
   resampleFilter: CatmullRom # cSpell:disable-line

docsy.dev/content/en/search.md

@@ -1,5 +1,6 @@
 ---
 title: Search Results
 layout: search
+outputs: [HTML]
 ---
 

docsy.dev/package.json

@@ -28,10 +28,14 @@
     "precheck:links:all": "npm run build",
     "precheck:links": "npm run build",
     "prepare-disabled": "cd .. && npm install",
+    "pretest:md-output": "npm run build",
     "prune:refcache": "node scripts/prune-refcache.mjs",
     "serve": "npm run _serve -- --minify",
-    "test": "npm run check:format && npm run check:links",
+    "test:base": "npm run check:format && npm run check:links",
+    "test": "npm run test:base && npm run test:md-output",
+    "test:md-output": "node --test 'tests/md-output/**/*.test.mjs'",
     "update:hugo": "npm install --save-exact -D hugo-extended@latest",
+    "update:md-goldens": "node tests/md-output/update-goldens.mjs",
     "update:packages": "npx npm-check-updates -u"
   },
   "devDependencies": {

docsy.dev/tests/md-output/golden.test.mjs

@@ -0,0 +1,21 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const goldenDir = fileURLToPath(new URL('./goldens/', import.meta.url));
+const publicDir = fileURLToPath(new URL('../../public/', import.meta.url));
+
+// `kind` is descriptive only (for readable test names); it doesn't affect test logic.
+const manifest = JSON.parse(
+  readFileSync(new URL('./goldens.json', import.meta.url), 'utf8'),
+);
+
+for (const { path, kind, covers } of manifest) {
+  test(`${path} (${kind}) — ${covers.join(', ')}`, () => {
+    const expected = readFileSync(join(goldenDir, path), 'utf8');
+    const actual = readFileSync(join(publicDir, path), 'utf8');
+    assert.equal(actual, expected);
+  });
+}

docsy.dev/tests/md-output/goldens.json

@@ -0,0 +1,37 @@
+[
+  {
+    "path": "index.md",
+    "kind": "home",
+    "covers": ["description", "body", "children"]
+  },
+  {
+    "path": "blog/index.md",
+    "kind": "section",
+    "covers": ["!description", "!body", "children"]
+  },
+  {
+    "path": "docs/index.md",
+    "kind": "section",
+    "covers": ["!description", "body", "children"]
+  },
+  {
+    "path": "docs/content/index.md",
+    "kind": "section",
+    "covers": ["description", "!body", "children"]
+  },
+  {
+    "path": "docs/get-started/index.md",
+    "kind": "section",
+    "covers": ["description", "body", "children"]
+  },
+  {
+    "path": "blog/2022/hello/index.md",
+    "kind": "page",
+    "covers": ["description", "body", "!children"]
+  },
+  {
+    "path": "fr/index.md",
+    "kind": "home",
+    "covers": ["description", "body", "children", "i18n:fr"]
+  }
+]

docsy.dev/tests/md-output/goldens/blog/2022/hello/index.md

@@ -0,0 +1,48 @@
+# Hello Docsy!
+
+> Welcome to the Docsy blog!
+
+---
+
+## Hello
+
+It may seem strange to see a "Hello" post from a project that's several years
+old, but as Docsy matures as a community-driven project, we thought it was time
+to (re)introduce ourselves and talk about what's new with your favorite (we
+hope) Hugo documentation theme!
+
+### Discuss amongst yourselves
+
+Our [Discussions](https://github.com/google/docsy/discussions) are really
+hopping lately! Don't miss our notice of the
+[upcoming deprecation of the Font-Awesome and Bootstrap git submodules](https://github.com/google/docsy/discussions/950)
+or our announcement of our
+[new governance model](https://github.com/google/docsy/discussions/798)!
+
+### Milestones, releases, and roadmaps
+
+We are planning our first official release of Docsy soon—check out the
+[milestones for 0.2.0](https://github.com/google/docsy/milestone/2). Got a
+suggestion for the roadmap? Open an
+[issue](https://github.com/google/docsy/issues).
+
+### Coming soon: project metrics
+
+Starting next month, we'll publish project metrics here on this blog.
+
+### Introducing the PSC
+
+Docsy now has a Project Steering Committee! The PSC members are [@chalin][],
+[@LisaFC][], [@geriom][], and [@emckean][]. If you're interested in serving on
+the PSC, open an [issue](https://github.com/google/docsy/issues) and nominate
+yourself!
+
+### Contribute to the blog!
+
+Also coming soon: contribution guidelines. Got an idea for a blog post? Open an
+[issue](https://github.com/google/docsy/issues)!
+
+[@chalin]: https://github.com/chalin
+[@LisaFC]: https://github.com/LisaFC
+[@geriom]: https://github.com/geriom
+[@emckean]: https://github.com/emckean

docsy.dev/tests/md-output/goldens/blog/index.md

@@ -0,0 +1,15 @@
+# Blog
+
+Section pages:
+
+- [Release 0.14.0 report and upgrade guide](/blog/2026/0.14.0/)
+- [Hugo 0.152.0-0.155.x upgrade guide](/blog/2026/hugo-0.152.0+/)
+- [Release 0.13.0 report and upgrade guide](/blog/2025/0.13.0/)
+- [Upgrade to Docsy 0.12.0 from 0.11.0](/blog/2025/0.12.0/)
+- [Docsy 2024 Review: Adoptions and Enhancements](/blog/2024/year-in-review/): Celebrating Docsy's 2024 growth in features and adoption, including a 57% usage increase, new features like dark mode, and improved internationalization support.
+- [Docsy 0.10.0 release report](/blog/2024/0.10.0/)
+- [Docsy 0.9.0 release report](/blog/2024/0.9.0/)
+- [Docsy priorities for 2024](/blog/2023/priorities-for-2024/)
+- [Upgrade to Docsy 0.7 & Bootstrap 5](/blog/2023/0.7.x/): A guide to upgrading to Docsy 0.7 and Bootstrap 5 with examples
+- [Migrating to Bootstrap 5.2](/blog/2023/bootstrap-5-migration/): An experience report in migrating Docsy from Bootstrap 4 to 5.2, with insights and instructions.
+- [Hello Docsy!](/blog/2022/hello/): Welcome to the Docsy blog!

docsy.dev/tests/md-output/goldens/docs/content/index.md

@@ -0,0 +1,20 @@
+# Content and Customization
+
+> How to add content to and customize your Docsy site.
+
+---
+
+Section pages:
+
+- [Adding Content](/docs/content/adding-content/): Add different types of content to your Docsy site.
+- [Look and Feel](/docs/content/lookandfeel/): Customize colors, fonts, code highlighting, and more for your site.
+- [Navigation and Menus](/docs/content/navigation/): Customize site navigation for your Docsy site.
+- [Search](/docs/content/search/): Let users search your Docsy site with a choice of configurable search options.
+- [Doc Versioning](/docs/content/versioning/): Customize navigation and banners for multiple versions of your docs.
+- [Docsy Shortcodes](/docs/content/shortcodes/): Use Docsy's Hugo shortcodes to quickly build site pages.
+- [Logos and Images](/docs/content/iconsimages/): Add and customize logos, icons, and images in your project.
+- [Print Support](/docs/content/print/): Making it easier to print entire sections of documentation.
+- [Analytics, User Feedback, and SEO](/docs/content/feedback/): Add Google Analytics tracking to your site, collect user feedback and learn about the page description meta tag.
+- [Repository Links and other page information](/docs/content/repository-links/): Help your users interact with page source and view page-source information.
+- [Taxonomy Support](/docs/content/taxonomy/): Structure the content using taxonomies like tags, categories, labels.
+- [Diagrams and Formulae](/docs/content/diagrams-and-formulae/): Add generated diagrams and scientific formulae to your site.

docsy.dev/tests/md-output/goldens/docs/get-started/index.md

@@ -0,0 +1,65 @@
+# Get started
+
+> Learn how to get started with Docsy, including the available options for installing and using the Docsy theme.
+
+---
+
+As you saw in our introduction, Docsy is a [Hugo](https://gohugo.io) theme,
+which means that if you want to use Docsy, you need to set up your website
+source so that the Hugo static site generator can find and use the Docsy theme
+files when building your site. The simplest way to do this is to copy and edit
+our example site, though we also provide instructions for adding the Docsy theme
+manually to new or existing sites.
+
+If you want to build and test your site locally you also need to be able to run
+Hugo itself, either by installing it and any other required dependencies, or by
+using our provided Docker container.
+
+This page describes Docsy's installation options and helps you choose the
+appropriate setup guide to get started.
+
+## Installation options
+
+Hugo offers multiple options for using themes, all of which are supported by
+Docsy.
+
+- **Adding the theme as a Hugo Module**:
+  [Hugo Modules](https://gohugo.io/hugo-modules/) are the simplest and latest
+  way to use Hugo themes. Hugo uses the modules mechanism to pull in the theme
+  files from the main Docsy repo at your chosen revision, and it's easy to keep
+  the theme up to date in your site. Our
+  [example site](https://github.com/google/docsy-example) uses Docsy as a Hugo
+  Module.
+- **Adding the theme as a Git submodule**: Adding the theme as a
+  [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) also lets
+  Hugo use the theme files from their own repo, though is more complicated to
+  maintain than the Hugo modules approach. This is the approach used in older
+  versions of the Docsy example site and is still supported.
+- **Cloning the theme files**: If you don't want Hugo to have to get the theme
+  files from an external repo (for example, if you want to customize and
+  maintain your own copy of the theme directly, or your deployment choice
+  requires you to include a copy of the theme in your repository), you can clone
+  the files directly into your site source.
+
+## Migration and backward compatibility
+
+If you have an existing site that uses Docsy as a Git submodule, and you would
+like to update it to use Hugo Modules, follow our
+[migration guide](/docs/updating/convert-site-to-module/). If you're not ready
+to migrate yet, don't worry! Your site will continue to work as usual.
+
+## Setup guides
+
+Follow the setup guide for your chosen approach. If you're new to Docsy and not
+sure which guide to follow, we recommend following the Use Docsy as a Hugo
+Module guide as a simple and easily maintained option.
+
+---
+
+Section pages:
+
+- [Use Docsy as a Hugo Module](/docs/get-started/docsy-as-module/): Learn how to get started with Docsy by using the theme as a Hugo Module.
+- [Other setup options](/docs/get-started/other-options/): Create a new Docsy site with Docsy using Git or NPM
+- [Deploy Docsy inside a Docker container](/docs/get-started/quickstart-docker/): Instructions on how to set up and run a local Docsy site with Docker.
+- [Basic site configuration](/docs/get-started/basic-configuration/): Basic configuration for new Docsy sites.
+- [Known issues](/docs/get-started/known_issues/): Known issues when installing Docsy theme.

docsy.dev/tests/md-output/goldens/docs/index.md

@@ -0,0 +1,91 @@
+# Welcome to Docsy
+
+<!-- markdownlint-disable-next-line no-space-in-links -->
+
+<span class="badge bg-primary text-bg-primary fs-6">v0.14.4-dev
+</span>
+
+Welcome to the Docsy theme user guide for version `v0.14.4-dev`. This
+guide shows you how to get started creating technical documentation sites using
+Docsy, including site customization and how to use Docsy's blocks and templates.
+
+## What is Docsy?
+
+Docsy is a theme for the [Hugo](https://gohugo.io/) static site generator that's
+specifically designed for technical documentation sets and has a lot of best
+practices built in. Use Docsy to get a working and reliable documentation site
+up and running fast, and then get back to focusing on great content for your
+users. [Learn more about Docsy](/about).
+
+In addition to the theme itself, we provide an
+[example site](https://github.com/google/docsy-example) that uses lots of Docsy
+features and has a useful skeleton site structure (with advice for what to put
+in it!) for a large technical documentation set. You can copy the entire site
+and edit it for your own projects, or just explore the site and its source to
+see what Docsy can do. The site you're currently reading also uses Docsy and is
+a useful example of a smaller Docsy docset: feel free to copy it or borrow from
+it if it suits your needs better than the "big" example.
+
+Docsy itself does **not** provide:
+
+- **Source hosting and management**: Our theme and site source files live on
+  [GitHub](https://github.com/), which is the simplest approach for most
+  projects. However, you can also keep your project files in
+  [GitLab](https://about.gitlab.com/),
+  [BitBucket](https://bitbucket.org/product), locally, or wherever you like. Be
+  aware that where your source files live may affect the Docsy features you can
+  use (such as letting users file documentation issues) and site deployment
+  options.
+- **Site deployment**: You can find out about deployment options in
+  [Previews and Deployment](/docs/deployment/). This site uses
+  [Netlify](https://www.netlify.com/).
+
+Docsy also doesn't actually generate your site's HTML files: that's Hugo's job!
+Hugo takes your Markdown or HTML doc source files and Docsy's theme files and
+builds them into a static site for deployment. You can find out more about Hugo
+and how it works in the [Hugo documentation](https://gohugo.io/documentation/).
+
+## Is Docsy for me?
+
+Docsy is particularly useful for medium to large technical documentation sets
+with 20+ pages of docs and/or multiple types of docs and pages: tutorials,
+reference documentation, blog posts, community pages, and so on.
+
+If you have a smaller project with only a couple of pages of documentation and
+hence simpler navigation needs, Docsy may be too heavyweight a solution for you.
+Instead, consider:
+
+- A simpler Hugo or Jekyll theme: find out what's available in GitHub Pages'
+  [built-in Jekyll options](https://pages.github.com/themes/) and the
+  [Hugo theme gallery](https://themes.gohugo.io/).
+- A good README file that tells users what your project does and links to some
+  examples.
+
+If you have a very large documentation project, our example site structure may
+not be sufficient either, though you can still use our theme, possibly with
+heavier customization.
+
+If you'd like to use Docsy's layouts but prefer to use Jekyll,
+[vsoch](https://github.com/vsoch) has created a
+[Docsy Jekyll port](https://github.com/vsoch/docsy-jekyll) that includes many of
+Docsy's features (though as this is a separate project it won't be automatically
+updated along with Docsy).
+
+## Ready to get started?
+
+Find out how to build and serve your first site in
+[Get Started](/docs/get-started/). Or visit the
+[example site](https://example.docsy.dev) and
+[its repo](https://github.com/google/docsy-example) and start exploring!
+
+---
+
+Section pages:
+
+- [Get started](/docs/get-started/): Learn how to get started with Docsy, including the available options for installing and using the Docsy theme.
+- [Content and Customization](/docs/content/): How to add content to and customize your Docsy site.
+- [Deployment and previews](/docs/deployment/): Deploying your Docsy site.
+- [Multi-language Support](/docs/language/): Support multiple languages in your site.
+- [Update Docsy](/docs/updating/): Keeping the Docsy theme up to date.
+- [Best Practices](/docs/best-practices/): Optional guidance and recommendations about organizing, authoring, and managing your technical documentation.
+- [Contribution guidelines](/docs/contributing/): How to contribute to Docsy