Fusion Help Docs

Fusion Help Documentation

Author, structure, and publish help docs (articles, release notes, FAQs) via fhelp CLI.

When to use

• Write help article for Fusion app
• Create/update release notes
• Set up docs folder structure + config
• Structure markdown for help system
• Publish/sync docs to Fusion environment
• Add FAQ entries
• Set up CI/CD pipeline to auto-publish

When not to use

• Modifying fusion-help-cli source (tooling/fusion-help-cli/)
• Changing Fusion.Services.Help backend API
• General markdown editing unrelated to Fusion Help
• Non-documentation tasks

Required inputs

Collect before creating:

Unknown app key → check app admin:

• CI: https://fusion.ci.fusion-dev.net/apps/app-admin
• Production: https://fusion.equinor.com/apps/app-admin

Look in "Admins" section — must be listed as admin to publish.

Instructions

1. Set up docs folder structure

Create folder layout:

docs/
  help/
    articles/                    # Markdown article files
      images/                    # Article images (PNG format)
    release-notes/               # Markdown release note files
      images/                    # Release note images (PNG format)
    faqs/                        # Optional: markdown FAQ body overrides
    help-articles.json           # Article config
    help-release-notes.json      # Release notes config (if using release notes)

Folder and config names are flexible — must match what you pass to fhelp.

2. Create the article config file

Create help-articles.json (tells CLI which articles to sync):

{
  "articles": [
    {
      "slug": "my-app-getting-started",        // Must match the .md filename (without extension)
      "title": "Getting Started",               // Display title in Fusion Help
      "appKey": "my-app",                       // Your Fusion app key
      "sortOrder": 1.0,                         // Controls display order (lower = first)
      "summary": "Learn how to get started.",   // Short description shown in article list
      "tags": ["getting-started", "onboarding"],// Searchable tags
      "relevantApps": []                        // Optional: other app keys where this shows
    }
  ]
}

Config field reference

3. Write article content

Create markdown files in the articles root folder. The filename (without .md) must match the slug in the config.

Article writing guidelines:

• Write for end-users of the Fusion app
• Use ##, ### for structure — avoid # (title comes from config)
• Place images in images/; reference with ![Alt text](images/my-screenshot.png)
• CLI auto-uploads images + rewrites paths to CDN
• Images must be PNG (CLI limitation)
• One topic per article
• Link related articles by title (platform handles deep linking)

Example article (docs/help/articles/my-app-getting-started.md):

## Overview

This guide walks you through the basics of using My App.

## Prerequisites

Before you begin, make sure you have:
- Access to the Fusion portal
- The correct role assigned to your user

## Step 1: Navigate to the app

Open Fusion and search for "My App" in the app launcher.

![App launcher](images/app-launcher.png)

## Step 2: Create your first item

Click the **New** button in the toolbar to create your first item.

## Need help?

Contact the team on Teams or check the FAQ section.

4. Create the release notes config file (optional)

Create help-release-notes.json if team publishes release notes:

{
  "releaseNotes": [
    {
      "slug": "my-app-v2-release",              // Must match the .md filename
      "title": "Version 2.0 Release",           // Display title
      "appKey": "my-app",                       // Your Fusion app key
      "publishedDate": "2026-03-14T00:00:00Z",  // Publication date (ISO 8601)
      "tags": ["release", "v2"],                // Searchable tags
      "relevantApps": []                        // Optional: other app keys
    }
  ]
}

Release notes config field reference

Example release note (docs/help/release-notes/my-app-v2-release.md):

## What's new in Version 2.0

### New dashboard

We've completely redesigned the dashboard with new charts and filtering capabilities.

![New dashboard](images/new-dashboard.png)

### Performance improvements

- Page load times reduced by 40%
- Search results now appear in under 1 second

### Bug fixes

- Fixed an issue where filters would reset on navigation
- Corrected date formatting in the export feature

5. Install and authenticate the CLI

Install from the Fusion Public feed:

dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli

Update an existing installation:

dotnet tool uninstall --global Fusion.Help.Cli
dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli

Authenticate via Azure CLI:

az login

CLI uses DefaultAzureCredentials — picks up az login session automatically.

6. Publish documentation

Sync articles:

fhelp article sync -f docs/help/help-articles.json -r docs/help/articles -e ci -v

Sync release notes:

fhelp releasenotes sync -f docs/help/help-release-notes.json -r docs/help/release-notes -e ci -v

Command flags:

Environment promotion order: ci → fqa → fprd (skip tr unless testing infrastructure).

Test in ci before promoting to fqa then fprd.

7. Set up CI/CD pipeline (recommended)

Automate publishing via Azure DevOps or GitHub Actions.

Azure DevOps pipeline example: