- 7 minutes to read

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

Add Article With Document Profile on the Articles overview: pick Contoso Integration Runbook, title the Article INT002 Contoso Orders: support runbook, write the Overview (Main Body) and Details sections, Save, and View the Article in read mode with both sections and the profile's Snippets, animated walkthrough (7.12)
Animated walkthrough: a new Article from a Document Profile, from the Add Article drop-down to the saved Article in read mode.

Understanding the Composite Workspace

graph TD Profile[fa:fa-list-check Document Profile] Article[fa:fa-newspaper Article using a Document Profile] Workspace[fa:fa-table-columns Composite Workspace] SnippetPart[fa:fa-lock Snippet Part - Profile-managed] ContentPart[fa:fa-pen Content Part - editable] MainBody[fa:fa-star Main Body] Preview[fa:fa-eye Live Preview] Raw[fa:fa-code Raw Tab] Profile -- Structures --> Article Article --> Workspace Workspace --> SnippetPart Workspace --> ContentPart ContentPart --> MainBody Workspace --> Preview Workspace --> Raw

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.

Workspace Element Behavior
Snippet Part Shown locked, marked "Profile-managed" — edit the Snippet itself to change it
Content Part An editable section — the Article's own text for that section
Main Body The one Content Part labeled as the Article's own main text
Required A Content Part the profile marks as Required — while it's empty, the workspace shows a Documentation health warning; the Article can still be saved
Live preview Shows the fully composed document as readers will see it
Raw tab Shows the full composed Markdown, Snippet Parts included
Layout Switches between horizontal and vertical, plus a fullscreen editor

Article editor of INT001 Orders: order-to-cash overview with the Contoso Integration Runbook profile: the Main Body Content Part in the WYSIWYG editor, the Profile-managed Snippet Part Next Step, a Markdown Details section, and the live preview (7.12)
Example of the composite workspace: the Main Body Content Part (here HTML, in the WYSIWYG editor), a Profile-managed Snippet Part with view and edit icons, a Markdown Content Part, and the live preview.

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.

Standard Technical Article Document Profile reader page with the Add Article using this Profile button highlighted (7.12)
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 editor, headed by the section name from the profile and marked Editable. A section is HTML only when HTML text came in with it: the Main Body of an HTML Article that gets a profile, or a section of a Template written as HTML. An HTML section uses the WYSIWYG editor; every other section, and every new one, is a Markdown text box. A section can't be switched between HTML and Markdown, and the reader shows both the same way. Both kinds have the same toolbar as every Article editor: Insert Image (from the Image Library), Insert File (from the File Library), 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 requires a Mapify license; if your Nodinite instance doesn't have the Mapify license, 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 Main Body Content Part Overview in the WYSIWYG editor, its toolbar ending with Insert Image, Insert File, Insert Article Link, Insert Snippet, Insert Icon, and Macro Help (7.12)
The editor toolbar shared by every Content Part; Insert Icon is shown only with a Mapify license.

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.

New 7.12 Ctrl+F and Ctrl+H open one find bar, Find in the content sections, that searches and replaces across all Content Parts at once. Generated and Snippet Parts are locked, so they are never searched or changed. See Find and Replace in the Editor.

Composite workspace with the find bar searching CONTOSO-SQL02, 1 of 2, over the Details Content Part, and the locked Snippet Part Next Step above it (7.12)
The find bar searches the Content Parts, here Details; the Profile-managed Snippet Part Next Step stays locked.

Fill in the Content Parts, check the live preview, and save. While a Content Part the profile marks Required is empty, the workspace warns Documentation health warning: required section(s) without content: ‹names›. Saving is still allowed. The Article saves anyway.

Choosing or Changing a Document Profile

Choose a profile in the Document Profile field of 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. Leave the field at No profile (free-form Article) for an Article without a profile.

Article editor of the free-form Article INT001 Orders: order-to-cash overview with the Document Profile field set to No profile (free-form Article) (7.12)
Example of the Document Profile field on a free-form Article, before a profile is chosen.

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. Saved sections with no match become Dangling Content Parts — nothing is ever merged or deleted without your say

Confirm Document Profile Change dialog for a free-form HTML Article: the text is kept as the Main Body and stays HTML with the WYSIWYG editor (7.12)
The confirmation says what happens before the profile is applied. From a free-form Article, the text becomes the Main Body (shown); when you switch profiles, it says which sections are kept and which become Dangling Content Parts.

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:

Action Effect
Move Move the text into a chosen section, before or after that section's existing text
Delete Remove the text, after a confirmation
Undo Take back a Move or Delete decision that hasn't been saved yet

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

Red Dangling Content Part banner with the unresolved section Owner and contacts, the Move into section and Position fields, and the Move and Delete buttons (7.12)
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 Overview (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.

Dangling Content Part banner where Owner and contacts will be moved after the text of Overview (Main Body) on save, with the Undo button (7.12)
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.

Usage card of the Contoso Integration Runbook Document Profile listing the three INT001 runbook Articles that use it (7.12)
Example of the Usage indicator listing where a Document Profile is currently used.

Next Steps