fusion-help-docs | SkillBundle

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

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

4. Create the release notes config file (optional)

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

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

5. Install and authenticate the CLI

Install from the Fusion Public feed:

Update an existing installation:

Authenticate via Azure CLI:

CLI uses DefaultAzureCredentials — picks up az login session automatically.

6. Publish documentation

Sync articles:

Sync release notes:

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:

GitHub Actions example:

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.

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