Writing Content
Learn how to write effective documentation using Markdown. This guide covers everything from basic syntax to advanced features and best practices.
Creating a Documentation Page
Step 1: Create the File
Create a new .md file in the resources/docs/ directory:
# Simple page
touch resources/docs/my-guide.md
# Nested page
mkdir -p resources/docs/guides
touch resources/docs/guides/advanced.md
Step 2: Add Frontmatter
Start every page with frontmatter to set the title and description:
---
title: My Guide Title
description: A brief description for SEO and previews
---
# My Guide Title
Content starts here...
Frontmatter Fields:
title- Page title (shown in browser tab, meta tags)description- SEO description (shown in search results, social media)
Step 3: Write Your Content
Use Markdown syntax to format your documentation. See sections below for comprehensive syntax examples.
Step 4: Access Your Page
Your page is automatically available at:
/docs/my-guide
/docs/guides/advanced
The URL matches the file path (without the .md extension).
Basic Markdown Syntax
Headings
Use # for headings. More # symbols = smaller heading:
# Heading 1 (Page Title)
## Heading 2 (Major Sections)
### Heading 3 (Sub-sections)
#### Heading 4
##### Heading 5
###### Heading 6
Paragraphs
Write paragraphs as plain text with blank lines between them:
This is a paragraph.
This is another paragraph. You need a blank line between
paragraphs for them to be separate.
Bold and Italic
**Bold text** or __also bold__
*Italic text* or _also italic_
***Bold and italic*** or ___also both___
Rendered:
Bold text
Italic text
Bold and italic
Lists
Unordered lists:
- First item
- Second item
- Third item
- Nested item
- Another nested item
Rendered:
- First item
- Second item
- Third item
- Nested item
- Another nested item
Ordered lists:
1. First step
2. Second step
3. Third step
1. Sub-step
2. Another sub-step
Rendered:
- First step
- Second step
- Third step
- Sub-step
- Another sub-step
Links
Internal links (to other documentation pages):
[Getting Started](getting-started)
[File Structure Guide](file-structure)
[Nested Page](guides/advanced)
External links:
[Laravel Documentation](https://laravel.com/docs)
[GitHub](https://github.com)
Links with titles:
[Visit Laravel](https://laravel.com "Laravel Framework")
Images
Add images to your documentation:
Image features:
- Click any image to view full-size (lightbox)
- Images automatically get top margin for spacing
- Responsive sizing (max-width: 100%)
- Alt text for accessibility
Best practices:
- Store images in
public/images/ - Use descriptive alt text
- Optimize image file sizes
- Use SVG for diagrams and icons
Advanced Formatting
Blockquotes
> This is a blockquote.
> It can span multiple lines.
>
> And include multiple paragraphs.
Rendered:
This is a blockquote. It can span multiple lines.
Code
Inline code:
Use the `composer install` command to install dependencies.
Rendered: Use the composer install command to install dependencies.
Code blocks:
```bash
npm install
npm run build
```
```php
<?php
namespace App;
class Example
{
public function hello()
{
return "Hello World";
}
}
```
Horizontal Rules
---
Renders as:
Tables
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1 | Data 2 | Data 3 |
| Data 4 | Data 5 | Data 6 |
With alignment:
| Left | Center | Right |
|:-----|:------:|------:|
| L1 | C1 | R1 |
| L2 | C2 | R2 |
Shortcodes
Add visual emphasis with custom shortcodes:
<div class="info">This is helpful information</div>
<div class="warning">This is important - pay attention!</div>
<div class="tip">Here's a pro tip for best results</div>
<div class="note">Additional context and references</div>
Rendered:
Reusable Components
Create reusable content blocks:
1. Create an include file:
resources/docs/includes/system-requirements.md:
## System Requirements
- PHP 8.2+
- MySQL 8.0+ or PostgreSQL 13+
- Node.js 18+
- 2GB RAM minimum
2. Include it in any page:
Before installing, check the requirements:
## System Requirements
- PHP 8.2 or higher
- MySQL 8.0+ or PostgreSQL 13+
- Composer 2.x
- Node.js 18+ and NPM
- 2GB RAM minimum
- 10GB disk space
Now proceed with installation...
Best Practices
Writing Style
Do:
- Write clear, concise sentences
- Use active voice ("Click the button" not "The button should be clicked")
- Break content into short paragraphs
- Use headings to organize content
- Add examples for complex concepts
- Use lists for steps and multiple items
Don't:
- Use jargon without explaining it
- Write walls of text without breaks
- Assume prior knowledge
- Skip important steps
- Forget to proofread
Organization
- Use descriptive headings - They appear in the Table of Contents
- Start with overview - Explain what before how
- Show examples - Code examples help understanding
- Link related content - Help users find more information
- Use visual elements - Shortcodes, images, code blocks
SEO Optimization
Every page should have:
---
title: Specific, Descriptive Title
description: Clear description of page content (150-160 characters)
---
- Include keywords naturally in content
- Use descriptive link text (not "click here")
- Add alt text to all images
- Create logical URL structure with subdirectories
Accessibility
- Use proper heading hierarchy (H1 → H2 → H3, don't skip levels)
- Provide alt text for images
- Write descriptive link text
- Use sufficient color contrast
- Keep sentences and paragraphs short and clear
Example Documentation Page
Here's a complete example showing best practices:
---
title: API Authentication Guide
description: Learn how to authenticate API requests securely using API keys and OAuth
---
# API Authentication
This guide explains how to authenticate requests to our API.
## Overview
All API requests require authentication. We support two methods:
- API Keys (recommended for server-to-server)
- OAuth 2.0 (recommended for user applications)
<div class="info">Choose the authentication method that best fits your use case!</div>
## API Key Authentication
### Step 1: Generate an API Key
1. Log into your account
2. Navigate to **Settings** → **API Keys**
3. Click **Generate New Key**
4. Copy and securely store your key
<div class="warning">API keys grant full access to your account. Never share them publicly or commit them to version control!</div>
### Step 2: Use Your API Key
Include your API key in the `Authorization` header:
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.example.com/v1/users
OAuth 2.0 Authentication
For user-facing applications, use OAuth 2.0:
[Include not found: oauth-setup]
Rate Limits
See Rate Limits for information about request quotas.
Troubleshooting
401 Unauthorized Error
Cause: Invalid or missing API key
Solution: Verify your API key is correct and included in the Authorization header.
403 Forbidden Error
Cause: Valid API key but insufficient permissions
Solution: Check that your API key has the required scopes enabled.
Next Steps
- API Reference - Complete endpoint documentation
- SDKs and Libraries - Official client libraries
- Rate Limits - Request quotas and limits
## Common Mistakes to Avoid
### Missing Blank Lines
❌ **Wrong:**
```markdown
Here's a list:
- Item 1
- Item 2
✅ Correct:
Here's a list:
- Item 1
- Item 2
Broken Links
❌ Wrong:
[See guide](guides/tutorial.md)
✅ Correct:
[See guide](guides/tutorial)
No Frontmatter
❌ Wrong:
# My Page
Content...
✅ Correct:
---
title: My Page
description: Page description
---
# My Page
Content...
Getting Help
- Review existing documentation files in
resources/docs/for examples - Check the Shortcodes guide for visual elements
- See Code Examples for syntax highlighting
- Explore Tables for table formatting
- Read Reusable Components for includes