App Development

App Development
Docs builder

Learn how to use the VTEX IO Docs builder.

The docs builder is used to publicly publish an app's documentation on the VTEX Developer Portal, allowing users to access relevant information about your app. Once the app is published, all Markdown content within the docs folder becomes available in the VTEX Developer Portal.

The content will be available in a URL of the following format:


Any app developer can make their documentation publicly available using the docs builder. So even if your app is not published to the VTEX App Store, you can take advantage of this convenience.

When using the docs builder, ensure no sensitive or private information is shared in the files under the /docs folder.

Folder structure

An app that uses the docs builder has a folder named /docs in its root directory. This folder serves as the repository for the application's documentation, where all documentation files are written in Markdown format (*.md files).

Following, you can find the basic app’s folder structure of an app using this builder:

┣ 📄

The is the main documentation file, where comprehensive information about the app is documented using Markdown syntax.

In addition to the, developers can provide supplementary guides in separate Markdown files. For instance, an additional guide named can be included to offer additional instructions or insights.

Each documentation file, including the and any supplementary guides, can be accessed via unique URLs within the VTEX Developer Portal. For example, the is accessible at{appvendor}.{appname}@{appversion}, while supplementary guides like can be accessed at{appvendor}.{appname}@{appversion}/OptionalSteps.


To begin using the docs builder in your app development, follow these steps.

  1. Add the docs builder to your app’s builder list in the manifest.json file, as the following:

"builders": {
"docs": "0.x"

  1. In the root directory of your app, create a /docs folder to manage your app’s documentation.
  2. Publish and deploy your new app version.
  3. Once you publish your app, the documentation will be available in the VTEX Developer Portal.

Versioning: Each app version will have its own documentation available at{appvendor}.{appname}@{appversion}, while accessing{appvendor}.{appname} will direct users to the latest version.

Use case examples

The docs builder plays a crucial role in making an app’s documentation accessible. As a best practice, it is recommended that an app include at least the file within the /docs folder.

As an example, check the folder structure of this builder in the Locale Switcher app and its public documentation in the Developer Portal.

For further guidance on structuring your app's documentation, refer to Documentation guidelines.

Photo of the contributor
+ 1 contributors
Was this helpful?
Suggest edits (Github)
Photo of the contributor
+ 1 contributors
On this page