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:

Markdown - a lightweight markup language for creating formatted text.
MDX - a superset of Markdown that allows you to use React components in your content.
Astro - a modern static site builder that supports MDX and other front-end technologies.
Starlight - a theme for Astro that provides a clean and modern documentation experience.
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.

Directorydocs/
- Directorydist/ production build output
  - …
- Directorypublic/ non-optimized, public assets
  - …
- Directorysrc/ main source code
  - Directoryassets/ optimized assets
    …
  - Directoryconfig/ astro/starlight configs
    …
  - Directorycontent/ markdown pages and content
    Directorydocs/ documentation content
    …
    Directoryi18n/ internationalized content
    …
  - Directorygenerated/ generated json files for dynamic content
    …
  - Directorylayouts/ components used to wrap pages
    …
  - Directorylib/ utility functions and shared code
    Directorycomponents/ reusable, custom components
    …
  - Directorypages/ non-documentation pages
    …
  - Directorystyles/ global styles and themes
    …

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
Manual

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.

First, install the required dependencies.
Terminal window
```
make docs-install
```
Next, run the development server.
Terminal window
```
make docs-dev
```
Open your browser and navigate to http://localhost:4321 to view the documentation.

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

First, cd into the docs directory.
Terminal window
```
cd docs
```
Next, install the required dependencies.
Terminal window
```
pnpm install
```
Run the development server.
Terminal window
```
pnpm dev
```
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.

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.

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/

Directoryconcepts/
- …
Directoryconfiguration/
- …
Directorycontributing/
- …
Directorydevelopment/
- …
Directoryfeatures/
- Directoryinstant-bananas/
  - index.md Write your documentation here
  - requirements.mdx You can add more pages in this directory
Directorystart-here/
- …
Directorytroubleshooting/
- …
Directoryworkflows/
- …

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/.

If you wish to add a top-level category, then one additional step is required for the category to appear in the sidebar.

Within the src/config/sidebar.ts file, you’ll need to add a new sidebar category object to the array, since the fine-grained control over top-level categories needs to be a bit more explicit.

const sidebar = [
  // ...
  {
    label: 'Concepts',
    items: [
      {
        autogenerate: { directory: 'concepts' },
      },
    ],
  },
  {
    label: 'A New Category',
    items: [
      {
        autogenerate: { directory: 'new-category' },
      },
    ],
  },
  {
    label: 'Features',
    items: [
      {
        autogenerate: { directory: 'features' },
      },
    ],
  },
  // ...
]

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.

Directoryfeatures/
- Directoryinstant-bananas/
  - Directoryassets/
    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.

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

Adding Translations

Currently, the documentation is only available in English. If you wish to add translations for other languages, we’ve already laid the ground work for you to do so.

Firstly, add a new folder within the src/content/i18n directory, and create your translated version of the markdown file into the same path as the original.

For example:

Directorysrc/
- Directorycontent/
  - Directorydocs/
    Directorystart-here/
    installation.mdx
  - Directoryi18n/
    Directoryzh-CN Country code here
    Directorystart-here/
    installation.mdx

We recommend simply copy/pasting the file and rewriting the text from there.

Learn more about the intricacies of translating Astro Starlight docs here.

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
Manual

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.

First, run the build command.
Terminal window
```
make docs-build
```
Finally, preview the output.
Terminal window
```
make docs-preview
```

And that’s it.

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

First, cd into the docs directory.
Terminal window
```
cd docs
```
Next run the build command.
Terminal window
```
pnpm run build
```
Finally, preview the build.
Terminal window
```
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.

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

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, test and serve the docs on github pages. 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.

This site was designed and developed by Aether Fox Studio.