equinor/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:

| Input | Required | Description | |-------|----------|-------------| | App key | Yes | The Fusion app key (e.g. my-app, resource-allocation-landingpage). User must be admin for this app. | | Content type | Yes | articles, release-notes, or faqs | | Docs root path | Yes | Where the team stores their docs (e.g. docs/help/) | | Target environment | For publish | ci, fqa, tr, or fprd |

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

| Field | Required | Type | Description | |-------|----------|------|-------------| | slug | Yes | string | Unique identifier. Must match a {slug}.md file in the articles root folder. Use kebab-case. | | title | Yes | string | Human-readable title displayed in Fusion Help. | | appKey | Yes | string | Fusion app key this article belongs to. You must be admin for this app. | | sortOrder | No | number | Controls display order. Lower numbers appear first. Default varies. Use decimals (1.0, 1.1, 2.0) for flexible ordering. | | summary | Yes | string | Short description shown in article listings. | | tags | No | string[] | Searchable tags for categorization. | | relevantApps | No | string[] | Additional app keys where this article should appear. |

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

| Field | Required | Type | Description | |-------|----------|------|-------------| | slug | Yes | string | Unique identifier. Must match a {slug}.md file in the release notes root folder. | | title | Yes | string | Release note title. | | appKey | Yes | string | Fusion app key. You must be admin. | | publishedDate | Yes | ISO 8601 date | When the release was published. | | tags | No | string[] | Searchable tags. | | relevantApps | No | string[] | Additional app keys. |

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:

| Flag | Description | |------|-------------| | -f, --file | Path to the JSON config file | | -r, --root | Path to the folder containing markdown files | | -e, --env | Target environment: ci, fqa, tr, fprd | | -t, --token | Override the access token (optional) | | -v, --verbose | Show detailed logging output | | --no-validation | Skip source system check — use with caution, can overwrite UI-created content |

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:

parameters:
  - name: environment
    type: string
    default: ci
    values: [ci, fqa, fprd]
  - name: azureSubscription
    type: string

steps:
  - checkout: self

  - script: |
      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
    displayName: "Install fusion help CLI"

  - task: AzureCLI@2
    displayName: "Sync help articles"
    inputs:
      azureSubscription: ${{ parameters.azureSubscription }}
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        fhelp article sync `
          -f ./docs/help/help-articles.json `
          -r ./docs/help/articles `
          -e "${{ parameters.environment }}" `
          -v

  - task: AzureCLI@2
    displayName: "Sync release notes"
    inputs:
      azureSubscription: ${{ parameters.azureSubscription }}
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        fhelp releasenotes sync `
          -f ./docs/help/help-release-notes.json `
          -r ./docs/help/release-notes `
          -e "${{ parameters.environment }}" `
          -v

GitHub Actions example:

name: Sync Help Documentation

on:
  push:
    branches: [main]
    paths: ['docs/help/**']

jobs:
  sync-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: Install fusion help CLI
        run: |
          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

      - name: Azure Login
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: '3aa4a235-b6e2-48d5-9195-7fcf05b459b0'
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: Sync articles
        run: |
          fhelp article sync \
            -f ./docs/help/help-articles.json \
            -r ./docs/help/articles \
            -e ci -v

8. FAQs (supplementary)

FAQs use an Excel-based workflow and require app-level access. This is a temporary solution best suited for scenarios where FAQs span multiple apps.

fhelp faq sync -f docs/help/faqs.xlsx -e ci -v

For most teams, managing FAQs through the Fusion Help Admin UI at https://fusion.equinor.com/apps/fusion-help-admin is simpler.

Expected output

• docs/help/ folder with articles, images, and config
• Markdown article file(s) with proper content
• Valid help-articles.json (+ optional help-release-notes.json)
• How to install, auth, and run fhelp
• CI/CD pipeline snippet (optional)

Troubleshooting

| Problem | Cause | Solution | |---------|-------|----------| | DefaultAzureCredential failed to retrieve a token | Not authenticated | Run az login | | 403 Forbidden | Not an admin for the app key | Check admin list at the app admin page, or verify the appKey in your config | | Article not created (skipped) | No matching .md file in root folder | Ensure filename matches slug exactly: {slug}.md | | Source system mismatch warning | Article was created via UI, CLI won't overwrite | Use --no-validation carefully, or use a different slug | | Images not uploading | Wrong format | Images must be PNG format |

Safety & constraints

• Never use --no-validation without understanding — can overwrite UI-created content
• Test in ci before publishing to fprd
• sourceSystem auto-set to Fusion.Help.Cli; CLI and UI articles have different source systems and won't conflict unless --no-validation is used
• Slugs must be globally unique — use app-specific prefix (e.g. my-app-getting-started)
• Never commit access tokens — use az login or pipeline service principals