Writing a Profile-Based Article

^{New 7.11}

When an Article uses a Document Profile, the Article editor becomes a composite workspace. Sections that come from Snippets stay locked and shared, the sections the profile leaves open are yours to write, and a live preview shows exactly what readers will see.

• ✅ Write only the sections that are actually yours to fill in
• ✅ See the fully composed document update live as you type
• ✅ Switch profiles safely — nothing is ever merged or deleted without your say
• ✅ Always know which text is your Article's own Main Body

Understanding the Composite Workspace

The Document Profile decides the sections; the composite workspace splits them into locked, Profile-managed Snippet Parts and editable Content Parts, with a live preview and a Raw tab showing the full composed Markdown.

Start a Profile-Based Article

The quickest way in is from the Document Profile itself: click Add Article using this Profile in its editor header, its reader page, or its row Action menu on the Document Profiles overview. The Article editor opens with that profile preselected and the composite workspace ready to fill in.

Starting a new Article from the reader page of the seeded Standard Technical Article Document Profile.

Other ways to start:

• Add Article dropdown > With Document Profile… on the Articles overview, to pick the profile first
• Create the Article from a profile-based Template, such as the seeded Standard Technical Base Template — the profile is preselected and each Content Part starts with the Template's text
• Open the Article editor with the profileId deep link

See Ways to Create an Article for every entry point.

Writing the Content Parts

Each Content Part is its own Markdown editor, headed by the section name from the profile and marked Editable. It has the same toolbar as every Article editor: Insert Image, Insert File, Insert Article Link, Insert Snippet, Insert Icon, and Macro Help. Each button opens a picker and writes the matching content token for you.

Insert Icon adds the same icons you use for Component Types inline in the text. It needs a product key with the Mapify feature pack; without it, the button isn't shown. See the Macros Reference for every icon source and size.

{ndx}/fa/far/fa-circle-exclamation Renew the certificate before it expires.
The certificate is stored in {ndx}/azure/app%20services/00049-icon-service-App-Service-Certificates.svg App Service Certificates.

Examples of a Font Awesome icon and an Azure service icon written inline by Insert Icon; spaces in the Azure category folder are URL-encoded as %20.

The editor toolbar shared by every Content Part; Insert Icon is shown only with the Mapify feature pack.

The composite editor labels the Main Body section directly, so it's always clear which text is the Article's own main text rather than a Profile-managed Snippet Part.

Fill in the Content Parts, check the live preview, and save. Every Content Part the profile marks Required must have content first; the Article can't be saved until it does.

Choosing or Changing a Document Profile

Choose a Document Profile in the Article editor to turn an existing Article into a composite workspace. The Article's current content is moved into the profile's Main Body, so nothing is lost and the other Content Parts start empty. This is why every profile with Content Parts must have exactly one Main Body.

Changing or removing the profile later works like this:

1. A confirmation explains the effect of the change before anything happens
2. Sections whose names match a section in the new profile are kept automatically
3. Sections with no match become Dangling Content Parts — nothing is ever merged or deleted without your say

The confirmation explains which sections are kept and which become Dangling Content Parts before the new profile is applied.

Note

This is different from editing the Document Profile itself. When someone edits the shared Document Profile's structure, every Article using it updates automatically. Dangling Content Parts only happen when an Article's own chosen profile is deliberately changed or removed.

Resolving Dangling Content Parts

A Dangling Content Part is text an Article wrote for a section that no longer exists in its current Document Profile. A red banner lists every dangling section, and you resolve each one before you can save:

Save stays disabled until every dangling section is resolved. The server refuses the save too, returning 409 Conflict while any Dangling Content Part remains.

Example of the Dangling Content Part banner after switching to a new Document Profile.

Undo a Decision Before You Save

Choosing Move or Delete doesn't change the Article straight away. The decision is only recorded, and the dangling section's card shows what will happen when you save, for example Will be moved after the text of main (Main Body) on save. Until you save, each card also has an Undo button that takes the decision back, so you can pick a different target section or keep the text dangling while you think.

A pending decision: the section is marked to move after the Main Body text on save, and Undo is still available because nothing has been saved yet.

See the Effect of a Change

Before you edit or delete a Snippet, Template, or Document Profile, the editor shows its Usage — where it's currently referenced — so you can see the effect of a change before making it. The reader shows the same information as Dependency Impact.

Example of the Usage indicator listing where a Document Profile is currently used.

Next Step

• Reading Articles
• Document Profiles

Related Topics

• Knowledge base Articles
• Snippets
• Templates
• Macros Reference