noted / includes / MarkdownReference.php

MarkdownReference.php in Noted! 2.0, at includes/MarkdownReference.php

143 lines 4.6 KB

Raw Download Zip

1	<?php
2
3	declare(strict_types=1);
4
5	namespace Noted;
6
7	/**
8	* Renders the “Supported Markdown” reference for the settings screen.
9	*
10	* Keeps copy and samples in one place; {@see Settings} only wires the field.
11	*/
12	final class MarkdownReference
13	{
14	/**
15	* Build the full HTML body for the Markdown reference settings tab.
16	*/
17	public static function settingsTabHtml(): string
18	{
19	$body = self::examplesHtml() . self::unsupportedSectionHtml();
20
21	return wp_kses_post(sprintf('<div class="noted-md-doc">%1$s</div>', $body));
22	}
23
24	/**
25	* Render the supported-syntax example blocks.
26	*/
27	private static function examplesHtml(): string
28	{
29	$output = '';
30	foreach (self::exampleSections() as $section) {
31	$output .= sprintf(
32	'<section class="noted-md-doc__block">
33	<h3 class="noted-md-doc__title">%1$s</h3>
34	<p class="noted-md-doc__intro">%2$s</p>
35	<pre class="noted-md-doc__sample"><code>%3$s</code></pre>
36	</section>',
37	esc_html($section['title']),
38	esc_html($section['intro']),
39	esc_html($section['sample'])
40	);
41	}
42
43	return $output;
44	}
45
46	/**
47	* @return list<array{title: string, intro: string, sample: string}>
48	*/
49	private static function exampleSections(): array
50	{
51	return [
52	[
53	'title' => __('Headings', 'noted'),
54	'intro' => __('Start the line with one to six # characters, then a space.', 'noted'),
55	'sample' => sprintf(
56	"%s\n%s\n%s",
57	'# Main title',
58	'## Section',
59	'### Subsection'
60	),
61	],
62	[
63	'title' => __('Bold and italic', 'noted'),
64	'intro' => __('Use asterisks or underscores. These can appear in the middle of a line.', 'noted'),
65	'sample' => implode("\n", [
66	'important',
67	'__also bold__',
68	'emphasis',
69	'_also italic_',
70	]),
71	],
72	[
73	'title' => __('Links', 'noted'),
74	'intro' => __(
75	'Labelled links, autolinks in angle brackets, or bare URLs on their own line '
76	. 'or after a space.',
77	'noted'
78	),
79	'sample' => sprintf(
80	"%s\n%s\n%s",
81	'[WordPress](https://wordpress.org)',
82	'<https://example.com>',
83	'See https://example.com for details.'
84	),
85	],
86	[
87	'title' => __('Lists', 'noted'),
88	'intro' => __(
89	'Unordered lines start with "- " (dash + space). Ordered lines start with "1. ", "2. ", '
90	. 'and so on. Indent with spaces to nest lists.',
91	'noted'
92	),
93	'sample' => implode("\n", [
94	'- First item',
95	'- Second item',
96	' - Nested item',
97	'',
98	'1. Step one',
99	'2. Step two',
100	]),
101	],
102	];
103	}
104
105	/**
106	* Render the "Not supported" callout listing Markdown features that
107	* the lightweight parser intentionally ignores.
108	*/
109	private static function unsupportedSectionHtml(): string
110	{
111	$items = '';
112	foreach (self::unsupportedBullets() as $text) {
113	$items .= sprintf('<li>%s</li>', esc_html($text));
114	}
115
116	return sprintf(
117	'<section class="noted-md-doc__block noted-md-doc__block--muted">
118	<h3 class="noted-md-doc__title">%1$s</h3>
119	<p class="noted-md-doc__intro">%2$s</p>
120	<ul class="noted-md-doc__list">%3$s</ul>
121	</section>',
122	esc_html__('Not supported', 'noted'),
123	esc_html__(
124	'Noted does not parse full CommonMark or GitHub-Flavored Markdown. Treat these as plain text:',
125	'noted'
126	),
127	$items
128	);
129	}
130
131	/**
132	* @return list<string>
133	*/
134	private static function unsupportedBullets(): array
135	{
136	return [
137	__('Fenced code blocks (triple backticks) and inline `code` ticks', 'noted'),
138	__('Images, blockquotes, horizontal rules, tables, footnotes', 'noted'),
139	__('Strikethrough, task checkboxes, and other extensions', 'noted'),
140	];
141	}
142	}
143