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.
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.
Use a note to provide supplementary information or helpful context.
Use a tip to share a useful recommendation, shortcut, or best practice.
Use an info callout to provide additional details or background information.
Use an important callout to emphasize information readers should not overlook.
Use a caution callout when an action requires care or additional consideration.
Use a warning callout to highlight a potential issue or significant risk.
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.
- Open the application
- Configure the required settings
- 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.
Open PowerShell as Administrator
Open the Start menu, search for PowerShell, right-click Windows PowerShell, and select Run as Administrator.
Set the execution policy
Run the following command to allow scripts to execute in the current PowerShell session:
Allow scripts in this sessionSet-ExecutionPolicy -Scope Process BypassRun the remediation script
Navigate to the script directory and execute the script:
Run WinUpdate Remediationcd $env:USERPROFILE\Desktop.\WindowsUpdateReset.ps1Verify the result
Restart the computer if required, then check whether the original issue has been resolved.
Navigation Cards
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
Knowledge Base
Step-by-step instructions for common technology tasks.
Operating Procedures
Operational procedures, compliance guidance, and best practices.
Submit a Ticket
Submit a formal support request.
Technology Services
Find university-wide IT support resources.
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
| Type | Example |
|---|---|
new | New |
updated | Updated |
deprecated | Deprecated |
beta | Beta |
success | Active |
warning | Pending |
danger | Blocked |
info | Informational |
default | Default |
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
CompleteUse 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 ScheduleUse 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 YearUse 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 ScheduleUse behind for goals that are progressing but delayed.
Justification: Renders with an amber left bar and badge.
Example Not Started Goal
Not StartedUse not-started for committed goals that have not yet begun.
Justification: Renders with a red left bar and badge.
Example Paused Goal
Paused / CancelledUse 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
CompleteExample of a completed goal inside a StrategicPlan wrapper.
Sample Active Initiative
On ScheduleExample of an in-progress goal.
Sample Delayed Initiative
Behind ScheduleExample of a goal that is behind schedule.
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)
Use the advance code block type for codes.
User Message (Green)
Use for content sent TO the end user (email replies, customer-facing messages).
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.
*** 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.
Use blue templates when resolving and closing a ticket.
Resolution Summary: [How the issue was resolved]
User Communication: [Confirmation sent to the user]
- 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.
- 🪟 Windows
- 🍎 macOS
- 🐧 Linux
Steps for Windows go here. Use triple-backtick code blocks with powershell for commands:
Get-Service -Name "Spooler"
Steps for macOS go here. Use bash for commands:
sudo launchctl list | grep -i print
Steps for Linux go here. Use bash for commands:
systemctl status cups
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.
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.
.\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)
This is a plain-text code block.
Use when there's no specific language.
🫧 Bash / Shell (Teal)
#!/bin/bash
echo "Deploying application..."
npm install
npm run build
🔵 PowerShell (Blue)
# 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)
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)
{
"name": "pvfa-it-docs",
"version": "1.0.0",
"scripts": {
"start": "docusaurus start",
"build": "docusaurus build"
}
}
🟪 YAML (Violet)
name: Deploy
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
🟠 TypeScript / JavaScript (Amber)
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 showing | Use this language |
|---|---|
| PowerShell scripts or commands | powershell |
| Bash / Linux / macOS terminal | bash |
| Python scripts | python |
| JSON config files | json |
| YAML config files | yaml |
| JavaScript / React / TypeScript | javascript or typescript |
| Generic text, command examples | text |
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 A | Column B | Column C |
|---|---|---|
| Row 1 Cell A | Row 1 Cell B | Row 1 Cell C |
| Row 2 Cell A | Row 2 Cell B | Row 2 Cell C |
| Row 3 Cell A | Row 3 Cell B | Row 3 Cell C |
IT Reference Table
| Shortcut | Action | Platform |
|---|---|---|
Cmd + K | Open command palette | macOS |
Ctrl + K | Open command palette | Windows |
Cmd + S | Save file | macOS |
Ctrl + S | Save file | Windows |
Cmd + Shift + P | Open command palette | macOS |
Ctrl + Shift + P | Open command palette | Windows |
Comparison Table
| Feature | Standard | Advanced | Enterprise |
|---|---|---|---|
| Users | 5 | 50 | Unlimited |
| Storage | 10 GB | 100 GB | 1 TB |
| Support | Community | 24/7 phone | |
| SLA | None | 99.5% | 99.99% |
The values in this comparison are illustrative examples, not actual service commitments.
6. Links
Use descriptive link text so readers understand where a link leads.
Internal Links
Link to another documentation page using its site-relative path:
External Links
Use descriptive text for external resources. External links automatically display a small arrow indicator (↗) and open in a new tab.
Link Best Practices
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
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
Replace placeholder images with approved, relevant images before publishing production documentation.
Linked Image
An image can link to another resource:
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.
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.mdxextension - 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
textas the language for generic command-line examples or structured data without syntax
Metadata
- Include frontmatter:
title,description,sidebar_label,sidebar_position - Update
last_reviewedwhen making substantive changes to a doc - Set
review_frequency_monthsbased 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 is a living reference. If you find a pattern that's missing or unclear, let us know so we can improve it.