Technical guide for contributors

Hugo Doks is a new tool that we're using for contributing to our documentation portal.

Contributing in desktop editors

Prerequisites

Before working with the documentation repository, ensure the following tools are installed:

• Node.js Follow this guide if you need help with the installation. Node.js is required to run commands for testing and generating content locally.
• Git
• Code Editor It's recommended that you install Visual Studio Code if you wish to use a desktop code editor. However, you can also use our browser editor if that's your preferred method.
• Repository access Request contributor access from Gustav or Mikkel Mansa.

Procedure

1. Clone the docs repo in your Visual Studio Code/GitHub editor.

Cloning is essentially the process of copying the content and structure of the help portal, in its current production state. There are multiple ways to perform cloning, one of them being the following:

• Use the Ctrl + Shift + P keybord combo to open Git commands in the search bar up-top.
• Select Git: Clone from the dropdown list.
• Provide the URL from the screenshot (https://github.com/navipartner/docs.git).
• Press Enter.
• You will also need to provide your account info and select the destination for the cloned repo.

2. Open the terminal, and provide the following commands:

     git config --global user.name "Your Name"
     git config --global user.email "your.email@example.com"

3. Open the Terminal, and ensure that the filepath is correct, i.e. that it leads to the folder in which the repo is stored.

   

4. Install dependencies by running npm install in your Terminal.

   npm install

   This ensures all required Node modules are available. Now, you can start working on the content.

5. Click the Source Control icon in the left sidebar.

   

6. Git Pull from the master branch on the server.

   

   This ensures that the project version clone you have locally is up to date.

7. Click the name of the branch in the bottom left corner of Visual Studio Code, then click Create New Branch in the dropdown that is displayed at the top of the screen.

   

8. Use the following nomenclature when creating new branches: topic/your_initials/short_description

   Example:

   topic/js/creating_new_articles

   

   This helps keep branches organized and avoids conflicts.

9. To create new files, choose the place within the menu in which it makes sense to place it, and use the following command in the Visual Studio Code Terminal: npm run create + filepath

   Example:

   npm run create docs/retail/reimbursement/how-to/setup/index.md

   

   Be mindful of the difference between the _index.md and index.md files specified below in the Useful information section.

10. Update metadata in the frontmatter of your .md file:

• Set the Weight value to control where the doc appears in the TOC.
• Add a Title.
• Add a Description.

Refer to the Contributor guide for more information on formatting, structure etc.

8. To test the changes you make on the help portal locally, use the following command:

   npm run start

   The website will be generated locally, most likely on http://localhost:1313/.

9. Once you're done editing the topic, commit and push your changes.

Working in the browser editor

1. Go to https://github.dev/navipartner/docs.
2. Pull the latest changes to ensure your main branch is up to date.
3. Navigate to the file you want to edit (content/docs).
4. Make your edits, then commit and push.
5. Open https://github.com/navipartner/docs in your browser, and click Compare & Pull Request to submit your changes.

Create new files in the browser editor

Prerequisites

• Node.js must be installed, along with its npm commands.

Procedure

1. In your Terminal, run:

   npm install

2. Then create the file:

   npm run create docs/retail/reimbursement/how-to/setup/index.md

3. Use the npm run create + filepath command to create new files, e.g. npm run create docs/retail/reimbursement/how-to/setup/index.md . Refer to the difference between the _index.md and index.md files specified below in the Useful information section.
4. Make sure the Weight parameter in the metadata section corresponds to the area of the table of contents that you wish to place the doc in.
5. Make sure you add a description in the corresponding parameter.
6. Make sure you've added a Title.
7. Once you're done editing, commit and push.

Useful information

A content folder is automatically a section if the folder has an index file called _index.md. This causes Hugo to create a navigable URL for the section. For example, if content/about-us/_index.md exists, Hugo would create xyzcompany.com/about-us/.

The sections can be nested as deeply as you want. The important thing to understand is that to make the section tree fully navigational, at least the lower-most section must include a content file. (i.e. _index.md).

_index.md vs index.md

• Branch bundle — Its index file is called _index.md. It can have “children,” such as nested folders. If there are additional .md files within, each will get its own navigable URL. As we hinted earlier, only a folder that’s a branch bundle can be a section. By default, Hugo treats its index file as a list of the section’s contents, but, as we’ll see, you can exercise more control over this.

• Leaf bundle — Its index file is called index.md and, at build time, becomes a regular web page, not a list. It can’t be a section, and therefore can have no “children.” Any additional .md file in a leaf bundle won’t get its own navigable URL Other items within a leaf bundle are page resources for the index.md file (more on that in the following example).

Formatting notes containing internal links

{{< alert icon="📝" text="Make sure to read <a href="/docs/retail/gettingstarted/major_tom/">Major Tom" />}}

Formatting notes containing external links

{{< alert icon="📝" text="The customer's Azure tenant needs to be <a href="https://learn.microsoft.com/en-us/azure/active-directory/conditional-access/howto-conditional-access-session-lifetime\">configured prior to using the cloud version so that their session can be automatically extended on the following login." />}}

Formatting links in text

Use shortcodes + rel path! [POS Named Action Profile]({{< ref "pos_named_action_profile/pos_named_profile.md" >}})

https://gohugo.io/content-management/shortcodes/

Referencing global images

Place images in the 'static' folder (NOT static/images), and then act as if they are located in the same folder as the article you're referencing them from.

Editing article body width

Edit the "width" param in the assets/scss/common/_global.scss file. Currently, it is set to 800px, and 900px would mess up with the table of contents.

Image resizing and formatting

https://hugomods.com/docs/images/

Example without shortcodes: <image src="Images/edit_icon.PNG" width="30" height="30">