fusion-help-docs（融合帮助文档）

Fusion Help Documentation

Use this skill to help app teams author, structure, and publish help documentation (articles, release notes, FAQs) to the Fusion Help system using the fhelp CLI.

When to use

• User wants to write a help article for their Fusion app
• User wants to create or update release notes
• User wants to set up the docs folder structure and config file for their app
• User needs help structuring markdown content for the help system
• User wants to publish/sync documentation to a Fusion environment
• User asks about FAQs or how to add FAQ entries
• User wants to set up a CI/CD pipeline to auto-publish help docs

When not to use

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

Required inputs

Before creating documentation, collect:

If the user doesn't know their app key, point them to:

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

Open the app and look for the "Admins" section — you must be listed as admin to publish articles.

Instructions

1. Set up docs folder structure

Create the standard directory layout in the team's repository:

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)

The actual folder names and config file names are flexible — they just need to match what you pass to fhelp. The above is a recommended convention.

2. Create the article config file

The config file tells the CLI which articles to sync and their metadata. Create help-articles.json:

{
  "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 in clear, concise language aimed at end-users of the Fusion app
• Use headings (##, ###) to structure content — avoid # as the title comes from config
• Use images to illustrate UI workflows — place them in the images/ subfolder
• Image references in markdown use standard syntax: ![Alt text](images/my-screenshot.png)
• The CLI automatically uploads images and rewrites paths to the Fusion CDN
• Images must be PNG format — this is a current CLI limitation
• Keep articles focused on a single topic or workflow
• Link to related articles by mentioning their title (deep linking is handled by the platform)

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)

If the team publishes release notes, create help-release-notes.json:

{
  "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

The CLI uses DefaultAzureCredentials — it will pick up your 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).

Always test in ci first before promoting to fqa and then fprd.

7. Set up CI/CD pipeline (recommended)

Automate documentation publishing in your Azure DevOps pipeline or GitHub Actions workflow.

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

When this skill completes, the user should have:

• A docs/help/ folder structure with articles root, images folder, and config file(s)
• One or more markdown article files with proper content
• A valid help-articles.json (and optionally help-release-notes.json)
• Knowledge of how to install, authenticate, and run fhelp to publish
• Optionally, a CI/CD pipeline snippet for automated publishing

Troubleshooting

Safety & constraints

• Never use --no-validation without understanding the consequences — it can overwrite content that was manually created through the Fusion Help Admin UI
• Always test in ci before publishing to fprd (production)
• The sourceSystem is automatically set to Fusion.Help.Cli — articles created by the CLI and articles created via the UI have different source systems and won't conflict unless --no-validation is used
• Slugs must be globally unique across all apps — use an app-specific prefix (e.g. my-app-getting-started)
• Do not commit access tokens to source control — rely on az login or pipeline service principals