Documentation

The Invoke AI website, including its documentation are all contained within the docs directory.

Prerequisites

The documentation is built using Astro Starlight. It’s suggested you familiarize yourself with the following technologies before getting started:

1. Markdown - a lightweight markup language for creating formatted text.
2. MDX - a superset of Markdown that allows you to use React components in your content.
3. Astro - a modern static site builder that supports MDX and other front-end technologies.
4. Starlight - a theme for Astro that provides a clean and modern documentation experience.
5. Vite - a fast development server and build tool for modern web projects.

Markdown powers the content of every page on the website (including the homepage), with additional help from MDX to make the pages more interactive with imported React components.

Navigating the Documentation

The documentation is organized into a file tree structure. It should be very familiar to anyone who has built modern web applications.

• Directoriodocs/

  • Directoriodist/ production build output

    • …
  • Directoriopublic/ non-optimized, public assets

    • …
  • Directoriosrc/ main source code

    • Directorioassets/ optimized assets

      • …
    • Directorioconfig/ astro/starlight configs

      • …
    • Directoriocontent/ markdown pages and content

      • Directoriodocs/ documentation content

        • …
      • Directorioi18n/ internationalized content

        • …
    • Directoriogenerated/ generated json files for dynamic content

      • …
    • Directoriolayouts/ components used to wrap pages

      • …
    • Directoriolib/ utility functions and shared code

      • Directoriocomponents/ reusable, custom components

        • …
    • Directoriopages/ non-documentation pages

      • …
    • Directoriostyles/ global styles; colors, tabs and buttons follow the app’s Classic theme (plugins/theme-tokens.mjs)

      • …

Development

If you’ve ever worked within a react, astro or similar node-based library or framework, you should feel familiar with most of the setup here.

If you’re adding a feature, new behavior or etc. that changes how users expect Invoke to work, we expect you to deliver your PR with associated docs to support it. To get started, follow the steps below.

Dev Environment

There are 2 main ways to get your development environment set up for documentation:

Make

Invoke’s makefile makes it easy to set up your development environment for documentation in only a couple of commands. You can run these from the root of the repository.

1. First, install the required dependencies.

   make docs-install

2. Next, run the development server.

   make docs-dev

3. Open your browser and navigate to http://localhost:4321 to view the documentation.

Manual

If you prefer good ol’ fashioned cd and pnpm commands, you can set up your development environment manually.

1. First, cd into the docs directory.

   cd docs

2. Next, install the required dependencies.

   pnpm install

3. Run the development server.

   pnpm dev

4. Open your browser and navigate to http://localhost:4321 to view the documentation.

If there’s another local server running on port 4321 prior to running this, then use the port specified in the output.

The docs’ colors come from the app’s theme, invokeai/frontend/webv2/src/platform/ui/theme/themes.ts. Saving that file restarts the dev server, so theme changes show up on their own; a change to plugins/theme-tokens.mjs, which turns the theme into the docs’ tokens, needs a manual restart.

Adding Pages

Located within the src/content/docs/ directory, this is where the documentation pages are stored and organized by category. These categories are file-based and are mirrored to the sidebar navigation.

Caution

Do not place your docs content contributions outside of the content directory, it will not be seen.

If you wish to add a new sub category to document a feature or a behavior, simply create a new directory within the relevant top-level category directory.

For example, if we wanted to document a new feature called “Instant Bananas”, we would create a new directory within src/content/docs/features/ like so:

src/content/docs/

• Directorioconcepts/

  • …
• Directorioconfiguration/

  • …
• Directoriocontributing/

  • …
• Directoriodevelopment/

  • …
• Directoriofeatures/

  • Directorioinstant-bananas/

    • index.md Write your documentation here
    • requirements.mdx You can add more pages in this directory
• Directoriostart-here/

  • …
• Directoriotroubleshooting/

  • …
• Directorioworkflows/

  • …

The way you organize your added pages dictates how the URL structure is generated for your documentation pages. In this example, the url for the index.md page would be https://invoke.ai/features/instant-bananas/, and the url for the requirements.mdx page would be https://invoke.ai/features/instant-bananas/requirements/.

The sidebar is split into topics, such as Get Started, Guide and Models, and each page shows the sidebar of its own topic. src/config/topics.ts lists the topics with the label, description, icon and landing page that the topic switcher shows, and src/config/sidebar.ts gives each topic its sidebar items, usually a directory to autogenerate from. A new page in an existing directory joins its topic automatically. A new top-level directory needs a topic, or must be added to an existing topic’s items, or the build fails with a message naming the page.

src/config/sidebar.ts

const topicItems = {
  // ...
  configure: [{ autogenerate: { directory: 'configuration' } }],
  'new-topic': [{ autogenerate: { directory: 'new-category' } }],
  // ...
};

Ordering Pages

To control the sidebar order, prefix a page file or directory name with a number and a dot, such as 01.projects.mdx or 04.Image Generation/. The sidebar lists prefixed siblings in numeric order, followed by any unprefixed siblings in their usual order. Among prefixed siblings, the number replaces sidebar.order. The prefix never appears in URLs or sidebar labels: concepts/04.Image Generation/01.introduction.mdx is served at /concepts/image-generation/introduction/, under a group labelled “Image Generation”.

Any leading run of digits followed by a dot counts as a prefix, so avoid names like 2.0-migration.mdx for other purposes. Don’t prefix the site’s root index.mdx: the link checker can’t match links to / against a prefixed root page. Two siblings that differ only in their prefix map to the same URL, and one of them is dropped.

Note

If you renumber a file while pnpm dev is running, its page can disappear until you restart the dev server or touch the file. Builds are not affected.

Page Metadata

Before your page becomes available, you will need to add frontmatter to define the page’s metadata such as its title, description, last update date, sidebar position, and etc.

Learn more about what frontmatter is and how to use it in your pages in the Starlight Documentation.

Once you have some basic frontmatter defined, you should be able to see it reflected in the sidebar and the page title.

Adding Images

We encourage adding imagery to your docs for creating a more engaging and visual experience for viewers. To add images, we prefer you to utilize an assets directory within the concerning category.

• Directoriofeatures/

  • Directorioinstant-bananas/

    • Directorioassets/

      • demonstration.webp
      • foobar.avif
    • index.mdx

The Astro image optimizer/renderer is quite flexible with image formats and sizes, but we’d prefer stored images to be at reasonable sizes (not 4k), and using optimized formats (webp, avif, jpeg).

To render the image, you’d just use a relative path in your markdown.

index.mdx

![Alt text here](./assets/demonstration.webp)

Translations

English is the source of truth: write and update the English pages and strings only. Translators work in Crowdin, which opens pull requests with their translations.

• Pages. Translations of the user-facing trees (start-here/, Users Guide/, configuration/, troubleshooting/ and the home page) land in src/content/docs/<locale>/, mirroring the English paths. Crowdin owns those directories, so don’t edit them by hand. A page without a translation shows the English page with a notice. A translation changes only prose: pnpm test fails one that adds or changes imports, components, {…} expressions, links or frontmatter other than titles and descriptions.
• Interface strings. Text in components and layouts comes from src/content/i18n/en.json. Add a key there and read it with Astro.locals.t('key'), or with the Trans component when the message contains markup such as a link. pnpm test fails when the code uses a key en.json lacks, or en.json has a key nothing uses.

Maintainers: the docs README covers Crowdin setup, adding a locale and reviewing a translation pull request.

Running a Build

Modifications to the docs may run fine on your machine, but as we’ve learned the hard way, GitHub pages flips that expectation completely. So, we’ve added some ways to ensure things work as expected before deploying.

Just like with the dev environment, you can build the docs one of two ways:

Make

Invoke’s makefile makes it easy to build the documentation in only a single command. You can run it from the root of the repository.

1. First, run the build command.

   make docs-build

2. Finally, preview the output.

   make docs-preview

And that’s it.

Deploy Target

The make command here sets the DEPLOY_TARGET environment variable to custom, so that the final output matches what you’d expect from the final deployment to https://v7.invoke.ai.

If you’d rather set a different deploy target, use the manual method.

Manual

If you prefer good ol’ fashioned cd and pnpm commands, or to have granular control over environment variables, you can run the following:

1. First, cd into the docs directory.

   cd docs

2. Next run the build command.

   pnpm run build

3. Finally, preview the build.

   pnpm run preview

   The preview url will be available on the same port as the dev server.

Generated Files

The Invoke API is always evolving, and quite large. Documenting all this by hand would be wildly impractical, so there’s a script we’ve set up to pull all that data and generate relevant json files into generated directory.

These files are used for the YAML Config and API Development pages. If you’re adding a feature that changes the yaml config, or the api then make sure to run pnpm run generate-docs-data to ensure tests pass, and that the docs are accurate in accordance to your updates.

App Search Index

The app’s command palette searches the docs from a copy of the docs index committed at invokeai/frontend/webv2/src/workbench/palette/docsSearchIndex.json. The build serves the index at /app-search.json (src/pages/app-search.json.ts). It lists the topics outside the Build group, with their labels, descriptions and landing pages, and each of their published pages, with its title, description, topic, and h2 and h3 headings. Developer and contributor pages are left out.

Resync the copy whenever a change reaches the index: adding, removing, moving or renaming a page; changing a page’s title, description, draft or pagefind frontmatter; adding, removing or renaming an h2 or h3 heading; or changing a topic in src/config/topics.ts. Rebuild, copy the index into the app, and commit the result:

cd docs
pnpm build
pnpm run sync-app-search-index

pnpm run check-app-search-index fails when the committed copy no longer matches a build.

Testing

The docs contain tests for the following:

Test	Description	Runs on…
Link Checker	Checks for invalid, malformed or misdirected internal link URLs	Dev Server, Build, Deploy
Verify Deployment Output	Check to ensure the asset and page paths have the expected base paths dependent on deploy targets	Build, Deploy
Check Docs Data	Checks to ensure the generated files are accurate	Deploy
Check App Search Index	Checks that the app’s copy of the docs search index matches the build	Deploy
Translation Checks	Checks that translated pages and interface strings add no code, markup or links and keep their placeholders (src/lib/translation-checks.mjs, part of pnpm test)	Deploy

GitHub Actions

Once you’ve submitted your updated docs, either via pull request or a main push to your own fork, the deploy-docs action will run.

The deploy-docs action will install the necessary dependencies, run a build and test it. Pushes to main then publish the site to https://v7.invoke.ai, served by GitHub Pages from the invoke-ai/docs-v7 repository. The v6 documentation at https://invoke.ai is built and deployed from the v6-bugfixes branch. Any failing deployments will require fixing before deploying.

Troubleshooting

All the styles are missing and the links are wrong, what happened?

This commonly happens when the base path and the deploy target are mismatched, check those first and then run your build again.

Redirects aren’t working on the production deployment, but they work locally, why?

Because GitHub Pages’ SSR environment is lackluster, and thus doesn’t handle backend redirects. We included a redirects configuration just in case GitHub ever grows a conscience, or if the docs ever get deployed someplace else.