tigergraph / gui-docs

Contributing to GraphStudio/Admin Portal Docs

It takes commitment from both writers and devs, as well as collaboration to create and maintain good documentation. Part of that commitment is to contribute to the documentation.

Writing a new page

To write a new page in Antora, you need to:

1. Write the plain text in Asciidoc in the pages directory of a module

   • You can write in your editor of choice. Many editors have plugins that allow you to view the source and preview the rendered result side-by-side. The VSCode plugin is sufficient in most cases, though it does not provide spellcheck or render images correctly.

   • IntelliJ’s Asciidoc plugin provides a beautiful preview and works with Antora’s file structure so images are also rendered correctly.

2. Add your page to the navigation file of that module.

If you are creating a new module, you will need to link the pages of the module in a navigation file, and then link that navigation file to the antora.yml file of the component.

If you are not familiar with Asciidoc, read Asciidoc documentation to learn how to author in Asciidoc.

Page, module & component

• page

  • Every entry in the left site navigation is a page. A page must exist in the pages directory of a module.

• module

  • The entries in the left site navigation that display without needing to be clicked to expand to show, along with all the pages inside it.

• component

  • All the modules and pages on a left site navigation.

Example 1. Page, module & component

TigerGraph Cloud (1)
|- Solutions (2)
     |-- Create a solution (3)

1. TigerGraph Cloud, along with all the modules and pages inside it, is a component

2. Solutions, along with all the pages inside it, is a module

3. Create a solution is a page.

Add images/assets

If you need to add images, files, or other assets to your document, add it to the family directory of a module (images, assets, etc.) If the directory doesn’t exist, create one.

Once you have added the image to the images family directory of a module, you can insert it by using the image macro:

Example 2. Block and inline image macro

image::name-of-file.png[Captions] (1)
image:name-of-file.png[Captions] (2)

1. Image macros with two colons are block images.

2. Image macros with one colon are inline images.

Read more about family directories here.

Editing an existing page

Click the Edit on GitHub button in the upper right corner of a page to make edits. When you are done, submit a pull request with a comment on why the edit was necessary.

Raise issues

If you find issues with the content of a page or module that cannot be easily fixed with a short edit, raise an issue in the GitHub repository.