Skip to content

Latest commit

 

History

History
75 lines (51 loc) · 3.17 KB

step-by-step.adoc

File metadata and controls

75 lines (51 loc) · 3.17 KB
Raw

Step-by-step guide for writing a new page

This is a step-by-step guide to writing a new page in Antora. In this guide, I will add a page named example.adoc to the GraphStudio documentation.

Video walk-through:

1. Fork the source repository

Fork the repository at https://github.com/lennessyy/tg-gui, and clone it in your local environment.

Check out the branch you want to work in. Since you are working in a fork, choose the branch that corresponds to the version you are creating documentation for.

2. Create the new document

Create the document in the pages directory of the module you are working in. For example, since I plan to add the page in the GraphStudio module, my file is created at gui/modules/graphstudio/pages/example.adoc.

3. Add the document to nav.adoc

nav.adoc is the navigation file for a module. You need to register your page on the navigation file in order for it to show up in the left site navigation.

  • If the file is at the root of the pages directory, then you only need to provide the filename.

  • If it is nested in another directory, you need to provide a relative path to the file from the root of the pages directory.

4. Add images

Add the images you will be using in the document to the images folder of the same module. In my example, this will be the graphstudios/images folder.

5. Write the document

Refer to Asciidoc Documentation to learn more about AsciiDoc syntax.

Note
 One thing to note is that it takes two carriage returns to start a new paragraph in Asciidoc. This allows you to start every sentence on a new line, and you can spot sentences that are too long.

5.1. Add images

To add images in a document, use the image macro(image:: or image:, followed by the name of the image, followed up square brackets). You do not need to specify any relative path

image macro
image::friday-meme.png[] (1)

Here is an image image:friday-meme.png[] for work on a Friday. (2)

  1. Two colons for a block image

  2. One colon for inline images

6. Add and commit your changes

Add and commit your changes to Git.

7. Load a local preview (Optional)

You can build a local preview of the doc site. Usually this is not necessary since you can already view the rendered output with an IDE plugin, but for the first few times of contributing, this might help you feel more comfortable about your commits.

7.1. Clone the build repository

Clone the repository at https://github.com/lennessyy/doc-site.

7.2. Edit the Antora Playbook

Change the url and branches in the antora-playbook.yml file to your local git repo.

Caution
 If created a new Git branch that you are using to preview, make sure that the antora.yml file at the root of your source repository do not have duplicate version names between all the branches you are using to build the site.

7.3. Run build

Follow the instructions in the README to build a local preview. In summary:

npm install
npm run build

Once the build finishes, you can open the static html files straight from your terminal or serve it with http-server.

8. Push and make a pull request

Push the changes to your fork and make a Pull Request.