Fusion Help Docs

作者 equinore8fd6cfaf8edMIT2 个星标收录于 2026年10月8日更新于 2026年10月8日仓库今天更新

Guides app teams through authoring, structuring, and publishing help documentation (articles, release notes, FAQs) using the fusion-help-cli. USE FOR: write help articles, create release notes, set up help docs, publish documentation, sync articles, configure help config file, maintain app help content. DO NOT USE FOR: building the CLI itself, modifying Fusion.Services.Help internals, or non-documentation tasks.

仅含说明Writing & ContentDevOps & Cloud
AI 生成的概览

指导团队使用 fhelp CLI 编写、组织并发布 Fusion 应用帮助文章、发布说明和常见问题。

功能
该技能引导应用团队建立 docs/help 目录结构，编写 Markdown 帮助文章和发布说明，并生成对应的 JSON 配置文件，用于登记 slug、标题、应用键和标签。它说明如何安装并验证 Fusion.Help.Cli dotnet 工具，如何针对 Fusion 环境运行文章、发布说明和 FAQ 同步命令，以及如何通过 Azure DevOps 或 GitHub Actions 流水线自动发布。它还涵盖常见同步与身份验证错误的排查方法，以及先在 ci 测试再发布到 fprd 等安全约束。
适用场景
适用于团队需要为 Fusion 应用撰写或重组帮助内容、创建或更新发布说明、添加 FAQ 条目，或为该文档设置自动发布流程的场景。不适用于修改 CLI 或后端源码，也与 Fusion Help 无关的一般 Markdown 编辑无关。
运行要求
需要从 Fusion Public NuGet 源安装 Fusion.Help.Cli dotnet 全局工具，并具备 .NET SDK，以及通过 az login 或流水线服务主体完成 Azure CLI 身份验证。发布需要对目标 Fusion 应用键拥有管理员权限，并能访问 Fusion 环境；可选的 CI/CD 使用需要 Azure DevOps 或 GitHub Actions。该技能附带模板和参考文档，但不包含脚本。

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:

InputRequiredDescription
App keyYesThe Fusion app key (e.g. my-app, resource-allocation-landingpage). User must be admin for this app.
Content typeYesarticles, release-notes, or faqs
Docs root pathYesWhere the team stores their docs (e.g. docs/help/)
Target environmentFor publishci, 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):

jsonc
{  "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
FieldRequiredTypeDescription
slugYesstringUnique identifier. Must match a {slug}.md file in the articles root folder. Use kebab-case.
titleYesstringHuman-readable title displayed in Fusion Help.
appKeyYesstringFusion app key this article belongs to. You must be admin for this app.
sortOrderNonumberControls display order. Lower numbers appear first. Default varies. Use decimals (1.0, 1.1, 2.0) for flexible ordering.
summaryYesstringShort description shown in article listings.
tagsNostring[]Searchable tags for categorization.
relevantAppsNostring[]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):

markdown
## 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:

jsonc
{  "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
FieldRequiredTypeDescription
slugYesstringUnique identifier. Must match a {slug}.md file in the release notes root folder.
titleYesstringRelease note title.
appKeyYesstringFusion app key. You must be admin.
publishedDateYesISO 8601 dateWhen the release was published.
tagsNostring[]Searchable tags.
relevantAppsNostring[]Additional app keys.

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

markdown
## 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:

powershell
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:

powershell
dotnet tool uninstall --global Fusion.Help.Clidotnet 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:

powershell
az login

CLI uses DefaultAzureCredentials — picks up az login session automatically.

6. Publish documentation

Sync articles:

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

Sync release notes:

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

Command flags:

FlagDescription
-f, --filePath to the JSON config file
-r, --rootPath to the folder containing markdown files
-e, --envTarget environment: ci, fqa, tr, fprd
-t, --tokenOverride the access token (optional)
-v, --verboseShow detailed logging output
--no-validationSkip 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:

yaml
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:

yaml
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.

powershell
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

ProblemCauseSolution
DefaultAzureCredential failed to retrieve a tokenNot authenticatedRun az login
403 ForbiddenNot an admin for the app keyCheck admin list at the app admin page, or verify the appKey in your config
Article not created (skipped)No matching .md file in root folderEnsure filename matches slug exactly: {slug}.md
Source system mismatch warningArticle was created via UI, CLI won't overwriteUse --no-validation carefully, or use a different slug
Images not uploadingWrong formatImages 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

来源与署名

来源：equinor/fusion-skills位于skills/fusion-help-docs提交e8fd6cf

许可证： MIT

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

更多来自 equinor/fusion-skills 的技能

Fusion Skills

equinor

作为入口，将 Fusion 技能生命周期请求路由到发现、安装、编写或质量代理。

AI & Agents2今天更新

Fusion Skill Authoring

equinor

指导创建或更新仓库技能，包含清晰的触发线索、支撑文件与评审流程。

AI & Agents2今天更新

Fusion Issue Authoring

equinor

通过分类问题类型、套用模板并在变更前确认，起草和更新 GitHub 议题。

Productivity & Workflow2今天更新

Fusion Rules

equinor

将编写 AI 编程助手规则文件的请求路由到对应编辑器的代理。

AI & Agents2今天更新

Fusion Infra Cli

equinor

使用 finf CLI 为 Fusion 服务数据库执行预配与迁移，包括 PR 临时数据库。

DevOps & Cloud2今天更新

Fusion Help Integration

equinor

将 Fusion 帮助中心接入应用页面，创建帮助文章 slug 常量并连接 PageLayout 帮助属性。

Software Development2今天更新

更多Writing & Content技能

Doc Coauthoring

anthropics

精选

引导用户通过三阶段工作流协作撰写文档、提案、技术规格与决策文档。

Writing & Content179K今天更新

Writing Guidelines

vercel-labs

精选

依据获取的写作指南审查文档与文稿，并报告风格问题。

Writing & Content32K5周前更新

Job Post Builder

anthropics

精选

根据职位需求生成招聘材料包：职位发布、面试指南与评分表、录用通知书模板。

Writing & Content27K今天更新

Write Spec

anthropics

精选

把功能想法或问题陈述转化为结构化 PRD，包含目标、用户故事、需求与指标。

Writing & Content27K今天更新

Draft Content

anthropics

精选

撰写博客文章、社交媒体帖文、邮件通讯、落地页、新闻稿和案例研究等营销内容。

Writing & Content27K今天更新

Brand Voice Enforcement

anthropics

精选

将现有品牌语调指南应用于销售和营销内容，并说明所采用的品牌选择。

Writing & Content27K今天更新