# Documentation The Invoke AI website, including its documentation are all contained within the `docs` directory. ## Prerequisites The documentation is built using [Astro Starlight](https://starlight.astro.build/). It’s suggested you familiarize yourself with the following technologies before getting started: 1. [Markdown](https://www.markdownguide.org/) - a lightweight markup language for creating formatted text. 2. [MDX](https://mdxjs.com/) - a superset of Markdown that allows you to use React components in your content. 3. [Astro](https://astro.build/) - a modern static site builder that supports MDX and other front-end technologies. 4. [Starlight](https://starlight.astro.build/) - a theme for Astro that provides a clean and modern documentation experience. 5. [Vite](https://vitejs.dev/) - 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](https://mdxjs.com/) 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](/content/development/documentation/#tab-panel-126/index.html) - [Manual](/content/development/documentation/#tab-panel-127/index.html) 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. 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. ### 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/ - Directory **instant-bananas/** - **index.md** Write your documentation here - **requirements.mdx** You can add more pages in this directory The way you organize your added pages dictates how the URL structure is generated for your documentation pages. ### 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](https://starlight.astro.build/reference/frontmatter/). ### 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/ - Directory **assets/** - **demonstration.webp** - **foobar.avif** To render the image, you’d just use a relative path in your markdown. ```markdown ``` ### 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. ### 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](/content/development/documentation/#tab-panel-128/index.html) - [Manual](/content/development/documentation/#tab-panel-129/index.html) 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. 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 ``` ## 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](/content/configuration/invokeai-yaml/index.html) and [API Development](/content/development/guides/api-development/index.html) 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.