In this article, you will find a step-by-step guide on how to add documentation to the Veracity for Developers GitHub repository.
Step 1: Cloning the documentation repository in GitHub
Step 2: Creating and editing pages
- Creating a new section
- Setting up a folder for images, downloads, and other assets
- Create and edit a documentation page wih: a. Markdown b. Linking images c. From markdown to Veracity for Developers
- Set up a table of contents
Step 3: Publishing pages by creating a pull request
All documentation happens trough the GitHub pages repository. You have to do some simple steps to actually be able to edit this repository. You will need a GitHub user and a code editor.
- Create a GitHub user at github.com
- Download GitHub Desktop and a code editor like Atom or Visual Studio Code
GitHub Desktop allows you to clone a version of the documentation pages to your computer, to then later merge it with the original repository. You can use any code editor to write the documentation.
- Create a forked copy of the documentation folders to edit on your computer.
To edit the documentation you need to first create a forked copy of the project that you can work with locally on your computer.
- Visit https://github.com/veracity/veracity-documentation
- Click the green clone button and select "Open in desktop"
- GitHub desktop will open up and ask you where you would like to clone the project locally. When you have selected the wanted path, click on "Clone"
This repository, all the documentation folders and will then be copied to your selected path on your computer and will be represented as a repository on your GitHub user account.
- You are now ready to create new documentation pages. If you have installed Atom or another code editor, GitHub Desktop should show you an option to directly open the document there.
Now that you have the document available on your computer locally you can start to add or edit the existing documentation.
Before creating a section, go to Documentation and ensure the section that you want to create is not already published on the Developer Portal. This is important because some sections are maintainted internally so you will not see them in GitHub files; as of August 2024, the sections Veracity Identity and API Explorer fall under this category.
To create a new section, you simply have to create a new folder inside the "sections" folder of the local clone of the repository. Locate the project on your computer. Name it with the topic that you want to publish on. The name of the folder has to be all lowercase letters. Be aware that the name of the folder will be the name of the URL path in Veracity for Developers.
Each section folder will contain other folders and page-files, that will be parsed into the final documentation page. In the next step you will be guided on how to fill up your section with content by adding an asset folder and assets that you can use to link to your page documents.
In the section folder you have created, simply create a new folder called "assets". We recommend you to upload images in png format, PDFs, and excel files into this folder. Make sure that all files are named in lowercase letters.
Here is an example of an asset folder with images and other files:
The easiest way to create pages is through using a code editor.
We recommend Atom and will show how you can use it through this editor.
Once you have Atom, or another code editor downloaded – open it to access the file structure of the forked project.
In the folder sidebar in Atom, Locate the project and the section folder where you want to create your documentation page. In Atom you can right-click and select "New document" to add it to this folder.
When you do this be sure to name the folder with all lower case letters and with the extension .md making it a Markdown file.
Now you can start to edit your document that will become the new page you are setting up.
The easiest way to start writing a document is to look at previously created documents to see the format that they are written in.
Here is an example of a very simple Markdown - .md document in Veracity for Developers:
Each of the Markdown documents starts with the author and a short description of the document. This part of the document will not be visible for readers of the document.
Each markdown document must have at least a Header 1 element starting with #.
Basic copy text is writing without any syntax, as shown in the example above.
Here are some other markdown elements you can use in the document.
Headers
`# This is an H1
Bullet Points
`* Red
- Green
- Blue`
Numbered Lists
1. Bird 2. McHale 3. Parish
Emphasis
*bold* _italics_
Links
[Visble copy](https://link.io/)
Images and downloadable files
After having added your .png image files with the correct naming in the "Assets" folder of the project, you can now add it to the different sections in the document.
This can be done with the following syntax:
The same goes for downloadable files.
<a href="assets/examplefile.xlsx" download>Name of file in Copy</a>
If you want to learn more about how to add other elements to your document visit Basic Syntax in Markdown.
Learn more about what format writing documents with this Markdown Guide.
After successfully merging your changes for the forked project, in Veracity for Developers, the markdown document will look like this:
The right-hand table of contents will be created from subtitles (with the ## syntax) so that the use easily can navigate to these parts of the page without too much scrolling.
The left-hand table of contents will contain the table of contents for the entire section, and we will guide you through how to make this now.
To make a table of contents, create a separate toc file in the section folder where you are working. You can do this the same way you created a file in your code editor. The file must be placed in the section where it belongs and have the name toc.json.
The easiest way to create a table of contents is just to copy it from another section, and then replace all the "text" and "href" elements with their respective page names and links. You can add elements to the toc with the following code:
{ "text": "Name of link to be shown in TOC", "href": "markdowndocument.md" }
You can see an example of a full table of contents here:
- Push Your Changes to Your Fork:
- Make sure all your changes are committed.
- Ensure all pages you added are reflected in the TOC in the correct section.
- Ensure all pages you added have author, description, and heading properties. For each page, go to its GitHub URL (in your forked repository) and see if it looks like the example below.
- Commit only changes to content (.md and .json file, any images you added in /assets). Avoid committing any .ds-store files.
- Push your changes to your forked repository on GitHub:
- Navigate to your forked repository:
- Go to your forked repository (veracity-documentation) on GitHub (in the browser), and open the Pull Requests tab. If you are unsure how to open your repository in a browser, in GitHub Desktop, select any file you want to commit, right-click with your mouse, and select the last option on the list.
- Open a Pull Request:
- Click on the "Pull requests" tab.
- Click the "New pull request" button.
- Select the branch of your forked repository that contains your changes.
- Compare it with the branch of the original repository you want to merge into (master).
- Create the Pull Request:
- Add a title and description for your pull request. Be clear and concise about the changes you made and why they are necessary.
- Click the "Create pull request" button.