authoring-sharepoint-markdown

Files (1)

• SKILL.md

SKILL.md (first lines)

# Authoring SharePoint Markdown

This skill turns Copilot-gathered content into a clean, well-structured markdown file that renders correctly in SharePoint's Markdown web part. It handles the format decisions so the author focuses on the content.

> **Scope:** Produces prose and Markdown only. Does not write code, scripts, or formulas of any kind.

---

## How SharePoint Renders Markdown

Before formatting, understand what SharePoint's Markdown web part supports and what it doesn't. Staying within these boundaries means no surprises when the page goes live.

**Renders reliably:**
- Headers (H1–H4; H5–H6 render but look identical to H4)
- Bold (`**text**`) and italic (`*text*`)
- Ordered and unordered lists, including nested lists (up to three levels)
- Tables (pipe-delimited; keep them narrow — wide tables scroll awkwardly on mobile)
- Links using the standard `[text](url)` format
- Blockquotes for callouts and notes
- Horizontal rules (`---`) as visual dividers
- Fenced code blocks (rendered in monospace; no syntax highlighting)

**Use with care:**
- Images: use absolute URLs (SharePoint CDN links or external sources); relative paths break outside the authoring context
- Task list checkboxes (`- [ ]`): render in some tenants, not others — avoid if readers need to rely on them

**Do not use:**
- Inline HTML (`<details>`, `<summary>`, `<div>`, etc.) — behavior is tenant-dependent and often stripped
- Footnotes — not supported
- Definition lists — not supported
- Emoji shortcodes (`:rocket:`) — use Unicode emoji directly (🚀) if needed

---

## Workflow: From Copilot Content to SharePoint Page

### Step 1 — Define purpose and audience

Before organizing any content, answer these two questions:

- **What is this document for?** (Reference, process guide, meeting record, knowledge article, project overview)
- **Who will read it?** (All staff, a specific team, new hires, external stakeholders)

The answers determine which template to use and how much context to include.

### Step 2 — Inventory the Copilot content

Review all Copilot-sourced material and sort it into three buckets:

- **Include as-is** — facts, summaries, or outputs that are accurate and complete
- **Include with edits** — content that is accurate but needs restructuring, simplification, or more concrete language
- **Exclude or verify** — any claims that may be hallucinated, outdated, or out of scope

Flag excluded items rather than silently dropping them so the author knows to verify or fill the gap.

### Step 3 — Choose a document type

Select the template that best matches the document's purpose (see Templates section below). If no single template fits, use the General Knowledge Article template as a base and adapt the section structure.

### Step 4 — Draft the document

Apply the chosen template. For each section:

- Lead with the most important information; put background and context after
- Use one heading per topic — do not cram multiple topics under one heading
- Turn any list of three or more parallel items into a bulleted or numbered list
- Use a table only when two or more attributes apply to each item in a list

### Step 5 — Apply SharePoint formatting

After drafting, do a formatting pass:

- Confirm heading levels don't skip (H1 → H2 → H3, never H1 → H3)
- Check that every table has a header row with the column names bolded or pipe-separated
- Replace any relative image paths with absolute URLs
- Remove any HTML tags
- Verify all links use `[display text](full URL)` format

### Step 6 — Deliver the output

Provide the complete markdown document, ready to paste into a SharePoint Markdown web part. Follow it with a brief list of any flagged gaps, unverified claims, or sections that need author input.

---

## Templates

### General Knowledge Article

Use for reference pages, FAQs, how-to guides, and most Copilot research outputs.

```
# [Topic Name]

> **Summary:** One or two sentences describing what this page covers and who it's for.

---

## Overview

[Context: why this topic matters, when to use this information]

---

## [Main Section 1]

[Content]

---

## [Main Section 2]

[Content]

---

## Key Takeaways

- [Concise summary point 1]
- [Concise summary point 2]

From zrosenfield/sharepoint-ai-skills, MIT.

More from zrosenfield/sharepoint-ai-skills