Complete Guide to
Contextra Labs Governance

1. Introduction

What Is Contextra

Contextra transforms Azure DevOps Wiki into a governed, enterprise-grade documentation platform. It layers lifecycle workflows, compliance tracking, rich WYSIWYG editing, offline support, and full audit trails on top of the native Wiki experience — without requiring any external backend or storage.

Every governed page follows a clear lifecycle:

Who Is Contextra For

• Engineering Teams — keep architecture and system docs current with governed workflows
• Architects — maintain architecture decision records (ADRs) and system diagrams under version control
• Compliance Officers — audit-ready documentation with approval records, attestation, and exportable evidence
• Tech Leads & Managers — visibility into documentation health, ownership, and review status
• PMOs — cross-project documentation governance dashboards and SLA compliance tracking

Key Capabilities

2. Getting Started

Installation

Contextra is installed directly from the Azure DevOps Marketplace:

1. Navigate to the Azure DevOps Marketplace
2. Search for "Contextra"
3. Click Get it free
4. Select your organization and confirm
5. An organization admin may need to approve the installation

Finding Contextra

Once installed, navigate to any Azure DevOps project:

1. Open your project
2. In the left navigation, go to the Home hub
3. Look for "Enterprise Docs" in the hub menu

First Launch

On first launch, Contextra will:

• Initialize the Azure DevOps SDK
• Detect the current project context
• Connect to the project's Wiki Git repository
• Load or create the governance metadata file (.docspace.json)

Interface Overview

The Contextra interface is divided into several key areas:

3. Page Management

Creating Pages

Click the New Page button in the command bar or page tree context menu. You will be prompted to choose a template:

• Blank Page — empty page with no predefined structure
• System Architecture — pre-structured template with sections for overview, components, data flow, and decisions
• Architecture Decision Record (ADR) — standard ADR format with status, context, decision, and consequences
• Component Documentation — template for documenting individual system components

Page Types

Editing Pages

Pages open in view mode by default. Click the Edit button in the command bar to enter edit mode. Changes are auto-saved every 2 seconds and committed to the Wiki Git repository automatically.

Organizing Pages

The page tree supports:

• Drag and drop — reorder and nest pages by dragging them in the tree
• Context menu — right-click a page for Move, Rename, and Delete actions

Deleting & Restoring

Deleting a page performs a soft delete. The page is removed from the active tree but tracked in the Governance Dashboard's deleted pages tab, where it can be restored if needed.

4. Rich-Text Editor

Contextra uses a TipTap-based WYSIWYG editor that provides a familiar word-processor experience while generating clean Markdown output committed to your Wiki repository.

Toolbar Groups

Slash Commands

Type / in the editor to open the slash command menu:

Markdown Shortcuts

The editor recognizes standard Markdown input shortcuts as you type:

• **text** — Bold
• *text* — Italic
• ~~text~~ — Strikethrough
• `code` — Inline code
• # through #### — Headings 1-4
• - or * — Bullet list
• 1. — Ordered list
• > — Blockquote
• --- — Horizontal rule

Code Blocks

Code blocks support syntax highlighting for a wide range of languages. Use the language selector dropdown or type the language name after the opening fence (```javascript).

Tables

Insert tables from the toolbar or slash command menu. Once inserted, tables provide a context menu (right-click) for adding/removing rows and columns, merging cells, and setting header rows.

Task Lists

Interactive task lists with checkboxes can be inserted from the toolbar. Each item can be toggled between checked and unchecked states directly in the editor.

Links & Bubble Menu

Select text to reveal the bubble menu with formatting options. Use the link button to insert or edit hyperlinks. Links support both external URLs and internal Wiki page references.

Editor Failover Chain

Contextra includes a resilient editor failover system to ensure you can always edit content:

1. TipTap WYSIWYG — primary rich-text editor (default)
2. Monaco Editor — VS Code-style Markdown editor (if TipTap fails to load)
3. Textarea — basic plain-text editing (if Monaco unavailable)
4. Read-Only View — rendered Markdown display (last resort)

5. Images & Diagrams

Image Upload

Contextra supports multiple methods for adding images to pages:

• Drag and drop — drop image files directly into the editor
• Upload button — use the toolbar image button to select files
• URL embed — paste a URL to embed external images
• Resizing — drag image handles to resize inline

Draw.io Integration

Contextra includes a fully embedded Draw.io diagram editor. Diagrams are stored directly in your Wiki Git repository and follow the same governance workflow as page content.

Available diagram templates:

Mermaid Diagrams

Contextra renders Mermaid diagram syntax in fenced code blocks. Supported diagram types:

• Flowchart — process flows with nodes and edges
• Sequence Diagram — interaction between participants over time
• State Diagram — state machine representations
• Class Diagram — UML class diagrams with relationships
• ER Diagram — entity-relationship models
• Gantt Chart — project timelines and task scheduling
• Pie Chart — proportional data visualization

Auto-Generated Table of Contents

Contextra automatically generates a table of contents from the heading structure of each page. The TOC updates in real-time as you add, remove, or reorder headings.

6. Lifecycle Governance

Lifecycle States

Every governed page has one of four lifecycle states:

Lifecycle Progress Bar

Each page displays a visual progress bar indicating its current position in the lifecycle. The bar highlights completed states and shows the active state with a pulsing indicator.

Governed vs. Non-Governed

Governance is opt-in per page. Non-governed pages function as standard Wiki pages without lifecycle tracking. A page can be switched to governed mode at any time from the Metadata Panel. Non-governed pages are clearly labeled in the page tree and dashboard.

State Transition Rules

7. Approval Workflow

Roles

• Page Owner — the person responsible for the page content and initiating reviews
• Reviewers — individual users assigned to review and approve changes
• Reviewer Groups — Azure DevOps groups whose members can act as reviewers

Submit for Review

When a page is ready for review, the owner clicks Submit for Review in the command bar. This transitions the page from Draft to In Review and notifies all assigned reviewers.

Approval Process

Each reviewer must:

1. Review the page content and any changes since the last approved version
2. Provide a change summary describing what was reviewed (mandatory)
3. Click Approve to record their approval

On approval, the system records:

• The approval record with reviewer identity and timestamp
• The version ID of the approved content
• The Git commit SHA for the exact content snapshot

Verification Badges

Approved pages display verification badges showing the approval status. If the page content changes after approval (e.g., through a direct Wiki edit), the badge updates to indicate that the current content differs from the approved version.

Approved Version Immutability

Once approved, the approved version is recorded as a Git commit SHA. Any subsequent edits automatically transition the page back to Draft. External edits made directly in Azure DevOps Wiki (outside Contextra) are detected automatically and flagged.

Review Intervals

Configure periodic review schedules for governed pages. Available intervals:

When a review interval elapses, the page owner is notified and the page is flagged for re-review on the Governance Dashboard.

8. Governance Dashboard

The Governance Dashboard provides a centralized view of documentation health across your entire project.

Key Metrics

• Health Score — overall documentation health as a percentage (based on approval currency, review compliance, and coverage)
• Risk Score — number and severity of documentation risks (overdue reviews, orphaned pages, stale content)
• Total Pages — all pages in the Wiki
• Governed Pages — pages with lifecycle governance enabled
• Non-Governed Pages — pages without governance (informational only)

Dashboard Views

• State Distribution — visual breakdown of pages by lifecycle state
• Coverage Rates — percentage of pages with owners, reviewers, and review intervals
• Quality Metrics — documentation quality indicators and trends

Page Filters

Filter the page list by lifecycle state, page type, owner, tags, or SLA status to find exactly the pages you need.

SLA Tracking

Pending reviews are tracked with color-coded badges:

Deleted Pages Tab

Soft-deleted pages appear in the Deleted Pages tab. From here, administrators can review what was deleted, when, and by whom — and restore pages if needed.

Audit Log Viewer

A filterable, searchable audit log shows all governance events: state changes, approvals, ownership changes, review submissions, and deletions. Each entry includes the actor, timestamp, and event details.

Compliance Reports

Export compliance data in multiple formats for audit evidence:

• CSV — raw data export for spreadsheet analysis
• PDF — formatted compliance report with charts and summaries
• Word (DOCX) — editable report document

Corruption Detection & Repair

The dashboard includes integrity checks that detect corrupted or inconsistent governance metadata. If issues are found, a one-click repair action reconciles the metadata with the actual Git state.

9. Collaboration

Page Comments

Every page has a Comments tab with threaded discussions. Comments support Markdown formatting and can be used for review feedback, questions, and general discussion about the page content.

@Mentions

Type @ in a comment to mention team members. Mentioned users receive a notification and can navigate directly to the relevant comment.

Work Item Linking

Link Azure DevOps work items to documentation pages. Linked items appear as inline chips displaying the work item ID, title, type, and current state. Chips update in real-time as work items progress through their workflow.

Work Item Picker

Use the built-in work item picker to search and link items by ID, title, or keywords. The picker supports filtering by work item type and state.

Notifications

Contextra sends notifications for key governance events:

• Page submitted for your review
• Page approved or changes requested
• Review interval approaching or overdue
• You were @mentioned in a comment
• A page you own was modified externally

Notifications appear via the bell icon in the top-right corner. Notification preferences can be configured per event type.

10. Version Control & History

Git-Based Versioning

Every page edit is committed to your Wiki's Git repository. This provides a complete, immutable history of all changes with author attribution, timestamps, and commit messages.

Version History Viewer

The History tab shows a chronological list of all versions for a page. Each entry displays the author, date, commit message, and governance state at the time of the edit.

Side-by-Side Diff Comparison

Select any two versions to view a side-by-side diff. Added content is highlighted in green, removed content in red. This is particularly useful during the review process to see exactly what changed since the last approved version.

Restoring Previous Versions

Any previous version can be restored with a single click. Restoring a version creates a new commit with the restored content (it does not rewrite Git history). The page returns to Draft state after restoration.

Approved Version Snapshots

When a page is approved, the exact Git commit SHA is recorded. This allows auditors to verify that the current content matches the approved version, or to retrieve the exact approved content at any future time.

11. Attestation & Read Receipts

How Attestation Works

Approved pages can require attestation from specific users or groups. When attestation is enabled, readers see an Acknowledge button confirming they have read and understood the content.

Attestation States

Acknowledgment Dialog

When clicking Acknowledge, a dialog confirms the action and records the user's identity, timestamp, and the specific version (commit SHA) being acknowledged.

Attestation Statistics

Page owners and administrators can view attestation statistics showing how many required users have acknowledged the current version, who is pending, and historical acknowledgment records.

12. Search & Discovery

Quick Search

Press Ctrl + K to open the quick search dialog. Contextra uses Fuse.js for fuzzy matching, so partial words and minor typos still return relevant results. Search covers page titles, content, tags, and metadata.

Advanced Filters

Refine search results with filters:

• State — Draft, In Review, Approved, Deprecated
• Type — Standard, Architecture, Component, ADR, Guide
• Owner — filter by page owner
• Tags — filter by assigned tags

Backlinks Panel

Every page shows a Backlinks panel listing all other pages that reference it. This helps you understand how documentation is interconnected and assess the impact of changes.

Related Pages

Contextra suggests related pages based on shared tags, similar content, and link relationships. Related pages appear in a sidebar panel for easy navigation.

13. Offline Support

How It Works

Contextra uses IndexedDB for local storage, enabling full offline editing capability. When you lose connectivity, changes are queued locally and synchronized when the connection is restored.

Pending Changes Indicator

A visual indicator in the command bar shows when you have unsynced changes. The indicator displays the number of pending operations in the sync queue.

Automatic Sync

When connectivity is restored, Contextra automatically processes the sync queue in order. Each pending change is committed to the Git repository with the original timestamp and author.

Conflict Resolution

If the same page was modified by another user while you were offline, Contextra uses a last-write-wins strategy. The system records both versions in Git history, ensuring no content is permanently lost.

Storage Details

IndexedDB stores data across three object stores:

14. Export

PDF Export

Export any page as a formatted PDF. The export uses print-optimized styling with proper headers, footers, page numbers, and table formatting. Diagrams and images are embedded in the output.

Word / DOCX Export

Export pages as Word documents for sharing with stakeholders who prefer editable formats. The DOCX file auto-downloads and preserves headings, tables, lists, and basic formatting.

CSV Export

The Governance Dashboard supports CSV export of compliance data, including page states, ownership, review dates, SLA status, and audit events. This is useful for importing into external compliance tracking tools or spreadsheets.

15. Administration

Governance Settings Hub

Project administrators can access governance settings via Project Settings → Governance Settings. This hub allows configuration of default review intervals, governance modes, and notification preferences.

Configuring Approver Groups

Define which Azure DevOps groups or teams can act as reviewers. Members of configured approver groups appear in the reviewer picker when setting up page reviews.

Configuring Deprecator Groups

Restrict who can deprecate pages by configuring deprecator groups. Only members of these groups can transition an Approved page to the Deprecated state.

Authorization

Contextra uses the Azure DevOps Graph API to resolve group memberships and user identities. All governance metadata is stored as files in the Wiki Git repository, inheriting the repository's existing access controls and permissions.

16. Metadata & Custom Fields

Page Metadata Panel

The right-side metadata panel displays and allows editing of key page properties:

• Page Title — the display name of the page
• Page Type — Standard, Architecture, Component, ADR, or Guide
• Owner — the user accountable for the page
• Lifecycle State — current governance state (read-only, changed via workflow)
• Review Interval — how often the page should be re-reviewed
• Tags — categorization labels for filtering and discovery
• Expiry Date — optional date after which the page is flagged for review or deprecation
• Azure Policy Link — link to a related Azure Policy for compliance mapping

Custom Fields

Add arbitrary key-value pairs as custom metadata. Custom fields are stored in the .docspace.json governance file alongside the page. These fields can be used for organization-specific metadata like cost center, classification level, or regulatory reference.

Tags Management

Tags are free-form labels that can be added to any page. They are used for filtering in the page tree, search, and governance dashboard. Tags are shared across the project for consistency.

Expiry Dates

Set an expiry date on a page to trigger automatic notifications when the date approaches. Expired pages are highlighted in the dashboard and can be configured to automatically transition to a review state.

Azure Policy Linking

Link documentation pages to Azure Policy definitions to establish traceability between your governance documentation and the actual policies enforced in your Azure environment.

Keyboard Shortcuts

Speed up your workflow with these keyboard shortcuts: