Skip to main content

Markdown Formatting Guide

This reference demonstrates the Markdown syntax, Docusaurus features, custom MDX components, and presentation conventions supported in PVFA IT documentation.

Use these examples when creating or updating documentation. Prefer consistent formatting, accessible content, descriptive headings, and examples that readers can easily follow.

Quick Reference

For a visual preview of each component, view this page on the live site. The code shown in examples can be copied and adapted for your own documentation.


1. Callouts​

Use callouts to highlight important information, provide context, or communicate risks.

Important: Use this blockquote format for a short, prominent announcement within the normal flow of a page.

note

Use a note to provide supplementary information or helpful context.

tip

Use a tip to share a useful recommendation, shortcut, or best practice.

info

Use an info callout to provide additional details or background information.

important

Use an important callout to emphasize information readers should not overlook.

caution

Use a caution callout when an action requires care or additional consideration.

warning

Use a warning callout to highlight a potential issue or significant risk.

danger

Use a danger callout to communicate a serious risk or potentially harmful outcome.


2. Lists and Checklists​

Checklists​

Use task lists to track prerequisites, document verification steps, or confirm completion.

Before beginning, ensure you have:

  • Completed the required prerequisites
  • Reviewed the relevant documentation
  • Verified that the required access is available
  • Items can also be pre-checked to show completed state

Numbered Steps​

Use numbered lists when the order of operations matters.

  1. Open the application
  2. Configure the required settings
  3. Verify that the process completed successfully

Bulleted Lists​

Use bulleted lists for unordered information.

  • First item
  • Second item
    • Nested sub-item
    • Another sub-item
  • Third item

3. Custom MDX Components​

PVFA IT documentation includes custom MDX components for presenting procedures, navigation options, status indicators, strategic plan entries, and ticket templates.

Procedural Steps​

Use the <Steps> and <Step> components when a procedure requires distinct, ordered instructions. Unlike a plain numbered list, steps get maroon circle markers, connecting vertical bars, and bold titles.

  1. Open PowerShell as Administrator

    Open the Start menu, search for PowerShell, right-click Windows PowerShell, and select Run as Administrator.

  2. Set the execution policy

    Run the following command to allow scripts to execute in the current PowerShell session:

    Allow scripts in this session
    Set-ExecutionPolicy -Scope Process Bypass
  3. Run the remediation script

    Navigate to the script directory and execute the script:

    Run WinUpdate Remediation
    cd $env:USERPROFILE\Desktop
    .\WindowsUpdateReset.ps1
  4. Verify the result

    Restart the computer if required, then check whether the original issue has been resolved.

Use <Cards> and <Card> to group related documentation links or direct readers to common resources. Supports 2, 3, or 4 column layouts.

Two-Column Layout​

Three-Column Layout​

Setup

Get started with the required configuration.

Configure

Apply the appropriate settings.

Deploy

Deploy and verify the solution.

Non-Linked Cards​

Cards without the link prop are informational only — they don't appear clickable.

Did You Know?

Cards can be used purely to group information visually, without being clickable links.

Flexible Icons

Any emoji works as an icon. Pick something that represents the content.

Status Badges​

Use <Badge> to communicate a concise status or distinguish the state of a feature. Badges are inline, so they flow with text.

This feature is New and available in the current release.

The legacy API is Deprecated. Use the supported replacement instead.

The dashboard is currently in Beta.

All Badge Types​

TypeExample
newNew
updatedUpdated
deprecatedDeprecated
betaBeta
successActive
warningPending
dangerBlocked
infoInformational
defaultDefault

Strategic Plan Goals​

Use <Goal> for individual strategic plan entries. Each goal has a status that controls the color accent and badge. Supported statuses: complete, on-schedule, deferred, behind, not-started, paused.

Example Complete Goal

Complete

Use the complete status when a goal has been fully achieved.

Justification: This status renders with a green left bar and badge.

Example On Schedule Goal

On Schedule

Use on-schedule for goals that are actively progressing on target.

Justification: Renders with a blue left bar and badge.

Example Deferred Goal

Deferred to Next Year

Use deferred when a goal is intentionally being pushed to a later planning cycle.

Justification: Renders with a cyan left bar and badge.

Example Behind Schedule Goal

Behind Schedule

Use behind for goals that are progressing but delayed.

Justification: Renders with an amber left bar and badge.

Example Not Started Goal

Not Started

Use not-started for committed goals that have not yet begun.

Justification: Renders with a red left bar and badge.

Example Paused Goal

Paused / Cancelled

Use paused when work has been stopped indefinitely or cancelled.

Justification: Renders with a maroon left bar and badge.

Filterable Strategic Plans​

Wrap a group of <Goal> components in <StrategicPlan> to add a filter bar that lets readers filter goals by status. The filter is URL-shareable (e.g., ?status=behind).

Example Section​

Sample Completed Initiative

Complete

Example of a completed goal inside a StrategicPlan wrapper.

Sample Active Initiative

On Schedule

Example of an in-progress goal.

Sample Delayed Initiative

Behind Schedule

Example of a goal that is behind schedule.

Sharing filtered views

The filter state is stored in the URL. Share a link like /docs/strategic-plan/2026?status=behind to send someone straight to the "Behind Schedule" view.

Ticket Templates​

Use <TicketTemplate> for copy-paste templates that your technicians use in TDX. Each template has a Copy button in the top-right that copies the body as clean plain text. Templates are color-coded by purpose.

Advance Code Block (Generic)​

Advance Code BlockAdvance Code Block Template

Use the advance code block type for codes.

User Message (Green)​

Use for content sent TO the end user (email replies, customer-facing messages).

User MessageExample User Message

Howdy,

This is an example message sent to an end user. The green outline indicates this content goes TO the customer.

Thanks, Technology Services - PVFA

Handoff (Amber)​

Use for internal handoffs between technicians or queues.

Handoff/Staff NoteExample Handoff

*** Internal Handoff ***

Use amber templates when transferring a ticket to another technician or queue.

Issue: [Brief summary]

Current Status: [Where things stand]

Remaining Work: [What the receiving tech needs to do next]

Resolution (Blue)​

Use for closing/resolution comments on completed tickets.

ResolvedExample Resolution

Use blue templates when resolving and closing a ticket.

Resolution Summary: [How the issue was resolved]

User Communication: [Confirmation sent to the user]

Writing good ticket templates
  • Use [PLACEHOLDER] brackets for fields techs need to fill in
  • Keep lines under ~70 characters for readability when pasted
  • Avoid Markdown formatting (**bold**, *italic*) inside the body — the asterisks will appear as literal text when copied
  • Use blank lines between sections — they survive the copy and improve readability

Tabs for Variants​

Use the built-in <Tabs> component when the same procedure has multiple variants (different operating systems, different tools, different paths). Users click the tab they need instead of scrolling through all variants.

Steps for Windows go here. Use triple-backtick code blocks with powershell for commands:

Windows Example
Get-Service -Name "Spooler"
Grouped tabs

Use the same groupId across multiple docs to sync tab selections. If a reader picks "macOS" on one page, every other page with groupId="example-os" will also show macOS.


Code and Technical Formatting​

Inline Code​

Use inline code for commands, filenames, configuration keys, application names when appropriate, and short code expressions.

Install the package using npm install lucide-react.

You can call getUserById(id) with a numeric ID.

Press Ctrl + K to open the command palette.

Code Blocks​

Use fenced code blocks for commands, scripts, configuration examples, and longer code samples. Always specify a language identifier — this enables syntax highlighting AND the color-coded outline that matches the language.

Without a Title​

npm install lucide-react
npm run start

#### With a Title

Use the `title` attribute to identify the file or purpose. The title appears in the color-coded header bar.

```typescript title="src/pages/index.tsx"
import React from 'react';
import Layout from '@theme/Layout';

export default function Home() {
return <Layout>Hello</Layout>;
}

Highlighting Specific Lines​

Use {line-numbers} to draw attention to specific lines. The highlight is visual only — copy-paste still gives clean plain text.

Pay attention to line 2
echo "line one"
echo "this line is highlighted"
echo "line three"

Single-Line Commands​

Even single commands benefit from a title — it tells the reader what they're running.

Run the remediation script
.\WinUpdate_Remediation.ps1

Code Block Color Reference​

Each language gets a distinct outline color so readers can scan a doc and identify code types at a glance. Here's the full reference:

🟤 Text / No Language (Maroon)​

Generic text output
This is a plain-text code block.
Use when there's no specific language.

🫧 Bash / Shell (Teal)​

deploy.sh
#!/bin/bash
echo "Deploying application..."
npm install
npm run build

🔵 PowerShell (Blue)​

Reset-Password.ps1
# Get the user from Active Directory
$user = Get-ADUser -Identity $username

if ($user) {
Set-ADAccountPassword -Identity $user -Reset
Write-Host "Password reset for $username" -ForegroundColor Green
} else {
Write-Error "User not found"
}

🟡 Python (Gold)​

process_users.py
import csv

def load_users(filename):
with open(filename, 'r') as f:
reader = csv.DictReader(f)
return list(reader)

users = load_users('users.csv')
print(f"Loaded {len(users)} users")

🟣 JSON (Purple)​

package.json
{
"name": "pvfa-it-docs",
"version": "1.0.0",
"scripts": {
"start": "docusaurus start",
"build": "docusaurus build"
}
}

🟪 YAML (Violet)​

.github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

🟠 TypeScript / JavaScript (Amber)​

src/utils/format.ts
export function formatDate(date: Date): string {
return date.toISOString().split('T')[0];
}

export function slugify(text: string): string {
return text.toLowerCase().replace(/\s+/g, '-');
}

Choosing the Right Language​

Use this mapping when adding code blocks to docs:

What you're showingUse this language
PowerShell scripts or commandspowershell
Bash / Linux / macOS terminalbash
Python scriptspython
JSON config filesjson
YAML config filesyaml
JavaScript / React / TypeScriptjavascript or typescript
Generic text, command examplestext

Keyboard Shortcuts​

Use the HTML <kbd> element to represent keys and keyboard combinations.

Press Cmd + Shift + P on macOS, or Ctrl + Shift + P on Windows.

To save, press Ctrl + S.


5. Tables​

Use tables to present structured information that readers need to compare or scan. Keep column headings descriptive and avoid tables when a simple list is easier to understand.

Basic Table​

Column AColumn BColumn C
Row 1 Cell ARow 1 Cell BRow 1 Cell C
Row 2 Cell ARow 2 Cell BRow 2 Cell C
Row 3 Cell ARow 3 Cell BRow 3 Cell C

IT Reference Table​

ShortcutActionPlatform
Cmd + KOpen command palettemacOS
Ctrl + KOpen command paletteWindows
Cmd + SSave filemacOS
Ctrl + SSave fileWindows
Cmd + Shift + POpen command palettemacOS
Ctrl + Shift + POpen command paletteWindows

Comparison Table​

FeatureStandardAdvancedEnterprise
Users550Unlimited
Storage10 GB100 GB1 TB
SupportCommunityEmail24/7 phone
SLANone99.5%99.99%

The values in this comparison are illustrative examples, not actual service commitments.


Use descriptive link text so readers understand where a link leads.

Link to another documentation page using its site-relative path:

Introduction

Use descriptive text for external resources. External links automatically display a small arrow indicator (↗) and open in a new tab.

Texas A&M Technology Services

Texas A&M campus map

Descriptive link text

Avoid "click here" or "read more" — screen readers announce links out of context, so the link text itself needs to make sense. For example:

❌ For more information on VPN setup, click here.

✅ See the VPN setup guide for more information.


7. Blockquotes​

Use blockquotes for attributed quotations or excerpts that need to be visually distinguished from the surrounding content.

This is a short, simple blockquote. It demonstrates the site's quotation styling with a maroon left bar and decorative quote mark.

A blockquote can also contain multiple paragraphs:

This blockquote contains the first paragraph.

This is the second paragraph. The quotation styling should remain consistent throughout the block.

— Example attribution

Blockquotes vs. admonitions

Use blockquotes for actual quotations. For emphasizing information to the reader (notes, tips, warnings), use admonitions (:::note, :::tip, etc.) instead — they're semantically clearer.


8. Images​

Use descriptive alternative text for meaningful images. Avoid relying on images alone to communicate essential information.

Standard Image​

Example placeholder image showing the PVFA building

Replace placeholder images with approved, relevant images before publishing production documentation.

Linked Image​

An image can link to another resource:

Example clickable placeholder image

Ensure the destination is relevant and the link's purpose is clear to readers.

Image Guidelines​

  • Always provide alt text that describes the image's content, not just "screenshot" or "image"
  • Use PNG for screenshots of software, UI, or anything with crisp text
  • Use JPG for photographs where file size matters more than crispness
  • Keep file sizes reasonable — images over 1MB slow down page loads
  • Reference local images by relative path (./files/screenshot.png) rather than external URLs when possible

9. Horizontal Rules​

Use a horizontal rule sparingly to separate major content sections when a heading alone is insufficient.

Content above the divider.


Content below the divider.

When to use horizontal rules

Horizontal rules are most useful when you have two unrelated sections that you want to visually separate without creating a new H2 heading. For most cases, a well-labeled heading is better.


10. Authoring Guidance​

When creating or updating documentation, follow these conventions:

Structure​

  • Use headings in a logical hierarchy (H1 → H2 → H3 → H4) — don't skip levels
  • Every page should have exactly one H1 (the page title)
  • Group related content under clear H2 sections

Content​

  • Prefer descriptive link text and meaningful image alternative text
  • Use numbered steps or the <Steps> component when sequence matters
  • Use callouts only when information warrants additional emphasis — too many callouts dilute their impact
  • Use realistic examples; clearly identify illustrative or placeholder values with [BRACKETS]

Components​

  • Use custom MDX components consistently and follow their supported properties
  • Any file using MDX components (<Steps>, <Goal>, <TicketTemplate>, etc.) must have the .mdx extension
  • Prefer components over raw HTML when both are available

Code​

  • Label code blocks with the appropriate language identifier
  • Add title="..." to code blocks when the file name or purpose adds clarity
  • Use text as the language for generic command-line examples or structured data without syntax

Metadata​

  • Include frontmatter: title, description, sidebar_label, sidebar_position
  • Update last_reviewed when making substantive changes to a doc
  • Set review_frequency_months based on how often the content changes

Accessibility​

  • Use proper heading hierarchy (don't skip from H2 to H4)
  • Provide alt text for all meaningful images
  • Use descriptive link text (not "click here")
  • Prefer the <kbd> element for keyboard shortcuts so screen readers announce them correctly

Need Help?​

If you have questions about documentation formatting or need help authoring a new page, reach out to PVFA IT via the contact information on the site homepage.

This document

This is a living reference. If you find a pattern that's missing or unclear, let us know so we can improve it.