Skip to content

Commit bef287c

Browse files
retlehsretlehs
authored
Add ?format=markdown query parameter support (#2)
* Add `?format=markdown` query parameter support * Add blueprint * Add tests
1 parent 7ac7bfc commit bef287c

File tree

5 files changed

+411
-114
lines changed

5 files changed

+411
-114
lines changed

‎.github/workflows/test.yml‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
name: Test Plugin
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- name: Checkout code
15+
uses: actions/checkout@v4
16+
17+
- name: Setup Node.js
18+
uses: actions/setup-node@v4
19+
with:
20+
node-version: '20'
21+
22+
- name: Setup PHP (for composer build)
23+
uses: shivammathur/setup-php@v2
24+
with:
25+
php-version: '8.1'
26+
tools: composer
27+
28+
- name: Install composer dependencies
29+
run: composer install --optimize-autoloader
30+
31+
- name: Build prefixed vendor
32+
run: composer run build
33+
34+
- name: Install wp-playground CLI
35+
run: npm install -g @wp-playground/cli
36+
37+
38+
- name: Start wp-playground with blueprint
39+
run: |
40+
echo "Starting wp-playground server in background..."
41+
PLUGIN_PATH=$(realpath .)
42+
echo "Plugin path: $PLUGIN_PATH"
43+
npx @wp-playground/cli server --mount="$PLUGIN_PATH:/wordpress/wp-content/plugins/post-content-to-markdown" --blueprint=blueprint.json &
44+
WP_PID=$!
45+
echo $WP_PID > wp-playground.pid
46+
echo "Started with PID: $WP_PID"
47+
48+
# Wait for wp-playground to be ready
49+
echo "Waiting for wp-playground to start..."
50+
for i in {1..30}; do
51+
if curl -s http://localhost:9400 > /dev/null; then
52+
echo "wp-playground is ready!"
53+
break
54+
fi
55+
echo "Waiting... ($i/30)"
56+
sleep 2
57+
done
58+
59+
- name: Wait for WordPress
60+
run: |
61+
# Wait for WordPress to be ready
62+
sleep 10
63+
64+
- name: Test single post markdown output
65+
run: |
66+
echo "Testing single post with ?format=markdown"
67+
68+
# Check if server is responding
69+
echo "Checking server status..."
70+
curl -v "http://localhost:9400/" || echo "Server not responding"
71+
72+
echo "Testing markdown endpoint..."
73+
response=$(curl -s "http://localhost:9400/hello-world/?format=markdown")
74+
echo "Response received: $response"
75+
76+
if [[ "$response" == *"# Hello world"* ]] && [[ "$response" == *"WordPress"* ]]; then
77+
echo "✅ Single post markdown query parameter test passed"
78+
else
79+
echo "❌ Single post markdown query parameter test failed"
80+
exit 1
81+
fi
82+
83+
- name: Test single post with Accept header
84+
run: |
85+
echo "Testing single post with Accept: text/markdown header"
86+
response=$(curl -s -H "Accept: text/markdown" "http://localhost:9400/hello-world/")
87+
88+
if [[ "$response" == *"# Hello world"* ]] && [[ "$response" == *"WordPress"* ]]; then
89+
echo "✅ Single post Accept header test passed"
90+
else
91+
echo "❌ Single post Accept header test failed"
92+
exit 1
93+
fi
94+
95+
- name: Test main feed markdown
96+
run: |
97+
echo "Testing main feed with ?format=markdown"
98+
response=$(curl -s "http://localhost:9400/feed/?format=markdown")
99+
100+
if [[ "$response" == *"Markdown Feed"* ]] && [[ "$response" == *"Hello world"* ]]; then
101+
echo "✅ Main feed markdown test passed"
102+
else
103+
echo "❌ Main feed markdown test failed"
104+
exit 1
105+
fi
106+
107+
- name: Test dedicated markdown feed
108+
run: |
109+
echo "Testing dedicated /feed/markdown/ endpoint"
110+
response=$(curl -s "http://localhost:9400/feed/markdown/")
111+
112+
if [[ "$response" == *"Markdown Feed"* ]] && [[ "$response" == *"Hello world"* ]]; then
113+
echo "✅ Dedicated markdown feed test passed"
114+
else
115+
echo "❌ Dedicated markdown feed test failed"
116+
exit 1
117+
fi
118+
119+
- name: Test content type headers
120+
run: |
121+
echo "Testing Content-Type headers"
122+
content_type=$(curl -s -I "http://localhost:9400/hello-world/?format=markdown" | grep -i "content-type")
123+
124+
if [[ "$content_type" == *"text/markdown"* ]]; then
125+
echo "✅ Content-Type header test passed"
126+
else
127+
echo "❌ Content-Type header test failed"
128+
exit 1
129+
fi
130+
131+
- name: Cleanup
132+
if: always()
133+
run: |
134+
if [ -f wp-playground.pid ]; then
135+
kill $(cat wp-playground.pid) || true
136+
fi

‎README.md‎

Lines changed: 45 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,58 @@
11
# Post Content to Markdown
22

3-
A WordPress plugin that returns post content in Markdown format when requested with an `Accept` header set to `text/markdown`.
3+
A WordPress plugin that returns post content in Markdown format when requested with an `Accept` header set to `text/markdown` or a `?format=markdown` query parameter.
44

55
## Requirements
66

77
PHP 8.1+
88

99
## Usage
1010

11-
### Single posts
11+
### Accept headers (ideal for LLMs)
1212

13-
Visit any single post on your site with the `Accept` header set to `text/markdown` to get the post content directly as Markdown.
13+
Send an `Accept: text/markdown` header to any of these URLs:
1414

15-
**Example:**
15+
- **Single post:** `https://example.com/post-slug/` → Returns post content as Markdown
16+
- **Single post with comments:** `https://example.com/post-slug/feed/` → Returns post + all comments
17+
- **Main feed:** `https://example.com/feed/` → Returns latest posts as Markdown
18+
19+
**Examples:**
1620

1721
```bash
18-
curl -H "Accept: text/markdown" https://example.com/my-awesome-post
22+
# Single post
23+
curl -H "Accept: text/markdown" https://example.com/my-awesome-post/
24+
25+
# Single post with comments
26+
curl -H "Accept: text/markdown" https://example.com/my-awesome-post/feed/
27+
28+
# Main feed
29+
curl -H "Accept: text/markdown" https://example.com/feed/
1930
```
2031

21-
### Markdown feed
32+
### Query parameters (accessible/shareable)
33+
34+
For browsers and sharing, use the `?format=markdown` query parameter:
35+
36+
- **Single post:** `https://example.com/post-slug/?format=markdown`
37+
- **Single post with comments:** `https://example.com/post-slug/feed/?format=markdown`
38+
- **Main feed:** `https://example.com/feed/?format=markdown`
39+
40+
**Examples:**
2241

23-
Access a feed of your posts in Markdown format at `/feed/markdown/`:
42+
```bash
43+
# View in browser
44+
https://example.com/my-awesome-post/?format=markdown
45+
46+
# Get post with comments
47+
https://example.com/my-awesome-post/feed/?format=markdown
48+
49+
# Get main feed
50+
https://example.com/feed/?format=markdown
51+
```
52+
53+
### Dedicated Markdown feed
2454

25-
**Example:**
55+
A dedicated Markdown feed is also available at `/feed/markdown/`:
2656

2757
```bash
2858
curl https://example.com/feed/markdown/
@@ -62,7 +92,12 @@ Welcome to WordPress. This is your first post. Edit or delete it, then start wri
6292

6393
**Feed URL structure:**
6494

65-
The Markdown feed is accessible at `https://yoursite.com/feed/markdown/`. Note that WordPress requires pretty permalinks to be enabled (Settings → Permalinks must be set to anything other than "Plain").
95+
Markdown feeds are accessible via:
96+
- `/feed/markdown/` - Dedicated Markdown feed
97+
- `/feed/?format=markdown` or `/feed/` with `Accept: text/markdown` - Main feed as Markdown
98+
- `/post-slug/feed/?format=markdown` or `/post-slug/feed/` with `Accept: text/markdown` - Single post with comments
99+
100+
Note that WordPress requires pretty permalinks to be enabled (Settings → Permalinks must be set to anything other than "Plain").
66101

67102
**Autodiscovery:**
68103

@@ -212,6 +247,7 @@ add_filter('post_content_to_markdown/markdown_output', function ($markdown, $ori
212247
The Markdown feed is cached for 1 hour by default to optimize performance. The cache is automatically cleared when:
213248
- A post is published or updated
214249
- A post is deleted
250+
- Comments are added, edited, or deleted (when comments are included in feed)
215251

216252
You can customize the cache duration using the `post_content_to_markdown/feed_cache_duration` filter.
217253

‎blueprint.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
3+
"landingPage": "/",
4+
"preferredVersions": {
5+
"php": "latest",
6+
"wp": "latest"
7+
},
8+
"steps": [
9+
{
10+
"step": "setSiteOptions",
11+
"options": {
12+
"permalink_structure": "/%postname%/"
13+
}
14+
},
15+
{
16+
"step": "activatePlugin",
17+
"pluginPath": "post-content-to-markdown/post-content-to-markdown.php"
18+
}
19+
]
20+
}

‎composer.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "roots/post-content-to-markdown",
33
"type": "wordpress-plugin",
4-
"description": "A plugin that converts post content to Markdown when requested with an `text/markdown` Accept header.",
4+
"description": "A WordPress plugin that serves post content as Markdown via Accept headers or query parameters.",
55
"license": "MIT",
66
"homepage": "https://roots.io/sage/",
77
"authors": [
@@ -12,7 +12,7 @@
1212
}
1313
],
1414
"scripts": {
15-
"build": "php-scoper add-prefix --force"
15+
"build": "vendor/bin/php-scoper add-prefix --force && cd vendor_prefixed && composer dump-autoload"
1616
},
1717
"require": {
1818
"league/html-to-markdown": "^5.1"

0 commit comments

Comments
 (0)