Pages

@squidoc/plugin-pages lets a Squidoc site publish custom Astro pages outside the documentation tree. Use it for homepages, changelogs, landing pages, about pages, release pages, and anything else that should not live in the docs sidebar.

Docs still come from docs/ and publish under docs.basePath, which defaults to /docs. Pages come from pages/ and publish from the site root.

docs/
  index.md
  configuration.md
pages/
  index.astro
  changelog.astro

That produces:

/docs/
/docs/configuration/
/
/changelog/

Install

The starter project includes the pages plugin by default. To add it manually:

npm install @squidoc/plugin-pages

import { defineConfig } from "squidoc";

export default defineConfig({
  plugins: [
    "@squidoc/plugin-seo",
    "@squidoc/plugin-pages",
    "@squidoc/plugin-codeblocks",
    "@squidoc/plugin-article-tree",
  ],
});

If the pages plugin is not installed, or if it is installed but no pages/index.astro exists, Squidoc generates a root page that redirects / to your docs index.

Create a Page

Create pages/index.astro:

---
export const squidoc = {
  title: "My Docs",
  description: "A custom homepage for my docs site.",
};
---

<section>
  <h1>My Docs</h1>
  <p>Read the latest documentation.</p>
  <a href="/docs/getting-started">Get started</a>
</section>

Pages are Astro components wrapped by the active Squidoc theme. You can write HTML, CSS classes, Astro expressions, and local component imports that Astro can compile statically.

Custom Directory

By default, custom pages live in pages/. You can change that with the plugin options:

export default defineConfig({
  plugins: [
    {
      name: "@squidoc/plugin-pages",
      options: {
        pagesDir: "custom-pages",
      },
    },
  ],
});

squidoc dev watches the configured directory, so edits in custom-pages/ rebuild the internal Astro project the same way edits in pages/ do.

Layouts

Squidoc currently supports exactly two page layouts:

• page: the default layout for custom pages. It includes the site navbar and footer, but no docs sidebar or article tree.
• docs: the documentation layout. It includes the docs sidebar, version selector, article tree slot, and docs content styling.

If layout is omitted, Squidoc uses page.

---
export const squidoc = {
  title: "Changelog",
  layout: "docs",
};
---

<h1>Changelog</h1>

Use docs only when the page should behave like part of the documentation experience. Most homepages, changelogs, and landing pages should use the default page layout.

Limits

Pages are static Astro pages. They are not API routes, SSR endpoints, or server-only pages. Route conflicts are not allowed: a page cannot publish to the same route as a documentation page.

For example, with the default docs base path, pages/docs.astro conflicts with the docs index at /docs and squidoc build fails with a clear route collision error.

Astro reserved routes such as 404.astro and 500.astro are not supported by the pages plugin. Squidoc fails the build with a clear error if those routes are present.

Dynamic Astro routes are not supported yet. Files such as pages/[slug].astro and pages/blog/[post].astro fail with a clear error instead of generating routes.

Page metadata must use a plain export const squidoc = { ... } object with string literal values for title, description, and layout. If Squidoc sees metadata it cannot parse, it logs a warning and falls back to defaults for the affected fields.