JetBrains Marketplace Help

Documentation Page

If your plugin needs not only a landing page with a list of features but user-facing documentation, the Documentation page is coming into play.

Unlike Custom pages, the Documentation page is designed to host documentation in a separate tab on the plugin's page.

This is not a single page but a full-fledged help instance with a structure, a table of contents, in-topic navigation, and an ability to set up search. Like the one you're reading right now. You can check some more examples here: Grazie Professional, Rust, and Edu Tools.

If you are asking yourself why you should bother about writing documentation for your plugin, here are a few tips:

  • Documentation makes your solution discoverable and searchable. When product documentation is online, external search engines will bring it to everyone who types the keywords into the search query.

  • Documentation helps you to stand out and communicate the features of a plugin better so that your customers get the most out of it.

  • Documentation makes your product look more professional and reliable and helps build trust in it.

  • Documentation is a way to support your current users. If they find answers in documentation, this will decrease the support load, which is crucial for a small team. Good documentation also often leads to a higher rating of a plugin.

Create documentation for your plugin

To add documentation for your plugin, install the Writerside plugin for IntelliJ IDEs and start writing docs inside your development environment.

You can use not only common Markdown but a variety of semantic markup elements and attributes tailored specifically to create documentation, like:

  • tabs

  • complex tables

  • videos

  • collapsible blocks

  • smart code snippets

  • tips, notes, and warnings.

On top of that, it has a built-in live preview that displays the docs in the way they will appear on the web, and a possibility to build docs locally.

  1. Download the plugin here.

  2. Create a documentation project alongside your plugins' code repository or in a separate docs repository.

  3. Write the actual content with the help of templates, live preview, and assistance.

  4. Commit and push the result.

For more information, refer to the Writerside plugin help.

Publish documentation

We will prepare build configurations on TeamCity, so you can run builds, check docs on staging and then promote updates to your documentation pages.

These run configurations include more than 100 automated tests that run during the build and check the integrity and quality of your content, and a detailed build log to let you know if something goes wrong.

  1. Open your documentation project and build the necessary help instance locally to produce a ZIP archive. Read more about it in Writerside documentation.

  2. Send us your plugin's ID (for example, here is the link to Writerside plugin and in this case the plugin ID is 20158), a link to your public repository and a ZIP archive name to our team via email writerside@jetbrains.com.

  3. Our team will create the TeamCity build configuration and send the link to you.

  4. You will be able to build the documentation, then publish it to staging to check.

  5. The documentation will appear in the Custom Pages section of the plugins' page.

    Custom pages view

    Click Preview to see how users will see it.

  6. Go back to the TeamCity build results and promote the docs to production.

Add search to the Documentation page

If you want to manage the search index yourself, do the following:

  1. Register on Algolia and create a new standalone application.

  2. Inside the application create a new index.

  3. In your documentation project, create the cfg/buildprofiles.xml file and in the <variables> tag specify the following:

    algolia-id

    Algolia Application ID

    algolia-index

    Algolia Index name

    algolia-api-key

    Algolia Search-Only API Key

    search-scopes-provider

    Use URL of your company or leave default https://www.jetbrains.com/

    For example:

    <buildprofiles xsi:noNamespaceSchemaLocation="https://helpserver.labs.jb.gg/help/schemas/mvp/build-profiles.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <variables> <algolia-id>TGW4GIW73X</algolia-id> <algolia-index>index_name</algolia-index> <algolia-api-key>29effd68f91893202311a653263f1fb8</algolia-api-key> <search-scopes-provider>https://www.jetbrains.com/</search-scopes-provider> </variables> <build-profile instance="instance_id"/> </buildprofiles>

  4. Send us the Admin API key and Algolia index name via email writerside@jetbrains.com. We will configure a TeamCity configuration to upload Algolia indexes to your account.

If you just want a working search, and don't want to manage the search index via a separate Algolia account, do the following:

  1. Request an Algolia application ID, index name, and API key from us via email writerside@jetbrains.com.

  2. In your documentation project, create the cfg/buildprofiles.xml file and in the <variables> tag specify the following:

    algolia-id

    Algolia Application ID

    algolia-index

    Algolia Index name

    algolia-api-key

    Algolia Search-Only API Key

    search-scopes-provider

    Use URL of your company or leave default https://www.jetbrains.com/

    For example:

    <buildprofiles xsi:noNamespaceSchemaLocation="https://helpserver.labs.jb.gg/help/schemas/mvp/build-profiles.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <variables> <algolia-id>TGW4GIW73X</algolia-id> <algolia-index>index_name</algolia-index> <algolia-api-key>29effd68f91893202311a653263f1fb8</algolia-api-key> <search-scopes-provider>https://www.jetbrains.com/</search-scopes-provider> </variables> <build-profile instance="instance_id"/> </buildprofiles>

  3. We will set up the TeamCity run configuration to upload Algolia indexes to our account.

Last modified: 21 March 2023
Custom Pages Semantic Versioning