Skip to content

Commit c105fa1

Browse files
Andrew Bakerclaude
Andrew Baker
and
claude
committed
Update help page title to "CloudScale Code Block: Online Help"
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 4ef9e4a commit c105fa1

File tree

2 files changed

+84
-42
lines changed

2 files changed

+84
-42
lines changed

‎docs/generate-help-docs.js‎

Lines changed: 41 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ helpLib.run({
1010

1111
pluginName: 'CloudScale Code Block',
1212
pluginDesc: 'Syntax highlighted code blocks with auto language detection, clipboard copy, dark/light mode toggle, a code block migrator from other plugins, and a read-only SQL query tool. Works as a Gutenberg block and as a [cs_code] shortcode.',
13-
pageTitle: 'Help & Documentation — Code Block',
13+
pageTitle: 'CloudScale Code Block: Online Help',
1414
pageSlug: 'code-block-help',
1515
adminUrl: `${process.env.WP_BASE_URL}/wp-admin/tools.php?page=cloudscale-code-sql`,
1616

@@ -22,33 +22,54 @@ helpLib.run({
2222

2323
docs: {
2424
'code-block': `
25-
<p>The <strong>CloudScale Code Block</strong> is a Gutenberg block and shortcode for displaying syntax-highlighted code in your posts and pages.</p>
25+
<p>The <strong>CloudScale Code Block</strong> is a registered Gutenberg block (<code>cloudscale/code</code>) and a <code>[cs_code]</code> shortcode for displaying syntax-highlighted code in WordPress posts and pages. Syntax highlighting is powered by <strong>highlight.js 11.11.1</strong> loaded from the cdnjs CDN, supporting over 190 languages with auto-detection.</p>
26+
<p><strong>Block and shortcode usage:</strong></p>
2627
<ul>
27-
<li><strong>Auto language detection</strong> — the plugin detects the programming language from the code content and applies appropriate syntax highlighting automatically.</li>
28-
<li><strong>Manual language selection</strong> — override the auto-detected language from the block toolbar dropdown.</li>
29-
<li><strong>Copy to clipboard</strong> — a copy button appears on hover, letting readers copy the full code snippet with one click.</li>
30-
<li><strong>Dark / Light mode toggle</strong> — readers can switch the code block theme between dark and light to match their preference. The setting is remembered via localStorage.</li>
31-
<li><strong>Line numbers</strong> — optionally display line numbers alongside the code.</li>
32-
<li><strong>Shortcode usage:</strong> <code>[cs_code lang="php"]your code here[/cs_code]</code></li>
33-
</ul>`,
28+
<li><strong>Gutenberg block</strong> — search for "CloudScale Code Block" in the block inserter (<kbd>/code</kbd>). Language, theme override, title, and line numbers are all configurable in the block sidebar panel.</li>
29+
<li><strong>Shortcode:</strong> <code>[cs_code lang="php" title="functions.php"]your code here[/cs_code]</code>. Supported attributes: <code>lang</code> (any highlight.js language alias), <code>title</code> (displayed as a filename label above the block), <code>theme</code> (overrides the site-wide theme for this block).</li>
30+
</ul>
31+
<p><strong>Features:</strong></p>
32+
<ul>
33+
<li><strong>Auto language detection</strong> — highlight.js analyses the code content and selects the most likely language. Accuracy is high for common languages (PHP, JavaScript, Python, SQL, Bash) but lower for short snippets. Override manually via the block sidebar when detection is wrong.</li>
34+
<li><strong>14 colour themes</strong> — Atom One (default), GitHub, Monokai, Nord, Dracula, Tokyo Night, VS 2015, VS Code, Stack Overflow, Night Owl, Gruvbox, Solarized, Panda, Shades of Purple. Each theme loads a dark and light variant; the toggle button switches between them. The selection is stored in <code>localStorage</code> per browser, so each reader's preference persists across page loads.</li>
35+
<li><strong>Copy to clipboard</strong> — uses the Clipboard API (<code>navigator.clipboard.writeText()</code>) with a fallback to <code>document.execCommand('copy')</code> for older browsers.</li>
36+
<li><strong>Line numbers</strong> — toggle per block. Line numbers are rendered via CSS counter to avoid polluting the copied text when a reader clicks Copy.</li>
37+
</ul>
38+
<p><strong>Requirements:</strong> WordPress 6.0+, PHP 7.4+. The block editor script uses <code>@wordpress/blocks</code> API version available in WordPress 5.8+, but full sidebar panel support requires 6.0.</p>`,
3439

3540
'sql-tool': `
36-
<p>The <strong>SQL Query Tool</strong> lets you run read-only SQL SELECT queries against your WordPress database directly from the admin — without needing phpMyAdmin or SSH access.</p>
41+
<p>The <strong>SQL Query Tool</strong> lets WordPress administrators run read-only SELECT queries against the live database from within wp-admin — without needing phpMyAdmin, Adminer, or SSH access. Results are displayed in a paginated table with column headers and query execution time.</p>
42+
<p><strong>Security model:</strong></p>
43+
<ul>
44+
<li>Access is restricted to users with the <code>manage_options</code> capability (Administrators only). All AJAX handlers verify a nonce generated with the action <code>cs_code_migrate_action</code>.</li>
45+
<li>Every query is validated by <code>is_safe_query()</code> before execution. This function: strips all block comments (including MySQL optimizer hint syntax <code>/*!...*/</code>) and line comments (<code>--</code> and <code>#</code>), rejects any query containing a semicolon (prevents statement stacking), blocks <code>INTO OUTFILE</code>, <code>INTO DUMPFILE</code>, and <code>LOAD_FILE</code> clauses, and only allows queries starting with <code>SELECT</code>, <code>SHOW</code>, <code>DESCRIBE</code>, <code>DESC</code>, or <code>EXPLAIN</code>.</li>
46+
<li>Queries are executed via <code>$wpdb->get_results()</code> with <code>suppress_errors(true)</code>. Any MySQL error is caught and displayed without exposing the full stack trace.</li>
47+
</ul>
48+
<p><strong>14 built-in quick queries</strong> organised into four groups:</p>
3749
<ul>
38-
<li>Only <code>SELECT</code> statements are allowed — the tool blocks any query that could modify data (<code>INSERT</code>, <code>UPDATE</code>, <code>DELETE</code>, <code>DROP</code>, etc.).</li>
39-
<li>Results are displayed in a formatted table with column headers.</li>
40-
<li>Row count and query execution time are shown below the results.</li>
41-
<li>Useful for quick data lookups, verifying plugin data, and debugging without leaving WordPress admin.</li>
50+
<li><em>Health &amp; Diagnostics</em>: database health check, site identity options, table sizes and row counts.</li>
51+
<li><em>Content Summary</em>: posts by type and status, site stats, latest 20 published posts.</li>
52+
<li><em>Bloat &amp; Cleanup</em>: orphaned postmeta, expired transients, revisions/drafts/trash, largest autoloaded options.</li>
53+
<li><em>URL &amp; Migration Helpers</em>: HTTP references, posts with HTTP GUIDs, old IP references, posts missing meta descriptions.</li>
4254
</ul>
43-
<p><strong>Note:</strong> this tool is only accessible to WordPress administrators.</p>`,
55+
<p><strong>Keyboard shortcuts:</strong> <kbd>Enter</kbd> or <kbd>Ctrl+Enter</kbd> runs the query. <kbd>Shift+Enter</kbd> inserts a newline.</p>`,
4456

4557
'migrator': `
46-
<p>The <strong>Code Block Migrator</strong> converts code blocks from other WordPress plugins (such as Crayon Syntax Highlighter, SyntaxHighlighter Evolved, and others) to CloudScale Code Blocks in one operation.</p>
58+
<p>The <strong>Code Block Migrator</strong> converts legacy code block shortcodes and HTML from other WordPress syntax highlighting plugins to CloudScale Code Blocks in a single batch operation — without manual copy-paste or post-by-post editing.</p>
59+
<p><strong>Supported source formats:</strong></p>
4760
<ul>
48-
<li><strong>Scan</strong> — finds all posts and pages containing shortcodes or HTML from supported legacy plugins.</li>
49-
<li><strong>Preview</strong> — shows what will be converted before making any changes.</li>
50-
<li><strong>Convert</strong> — replaces the old shortcodes/HTML with <code>[cs_code]</code> shortcodes, preserving the code content and language attribute where possible.</li>
61+
<li>WordPress core <code><!-- wp:code --></code> blocks — preserves language class attributes where present.</li>
62+
<li>WordPress core <code><!-- wp:preformatted --></code> blocks.</li>
63+
<li><code><!-- wp:code-syntax-block/code --></code> blocks from Code Syntax Block plugin.</li>
64+
<li>Legacy <code>[code]</code>, <code>[sourcecode]</code>, and similar shortcodes — language attribute is preserved if present.</li>
5165
</ul>
52-
<p>Always take a backup before running the migrator.</p>`,
66+
<p><strong>Migration workflow:</strong></p>
67+
<ol>
68+
<li><strong>Scan</strong> — queries <code>wp_posts</code> for all posts and pages whose <code>post_content</code> contains a <code>LIKE</code> match on the supported block comment and shortcode patterns. Results are displayed as a list with post title, status, date, and block count.</li>
69+
<li><strong>Preview</strong> — for each post, shows a before/after diff of the exact content changes that will be made. No database writes occur at this stage.</li>
70+
<li><strong>Migrate single</strong> — converts one post at a time. Calls <code>$wpdb->update()</code> to write the converted <code>post_content</code> and immediately flushes the post cache with <code>clean_post_cache()</code>.</li>
71+
<li><strong>Migrate all</strong> — processes every remaining post in a single AJAX request. For large sites (&gt;500 posts), run this during low-traffic periods as it holds a series of database write locks.</li>
72+
</ol>
73+
<p><strong>Always take a backup before running the migrator.</strong> The conversion modifies <code>post_content</code> directly in the database. If the output is not what you expected, restore from backup — there is no undo button.</p>`,
5374
},
5475
}).catch(err => { console.error('ERROR:', err.message); process.exit(1); });

‎docs/help-page.html‎

Lines changed: 43 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -47,46 +47,67 @@ <h1>CloudScale Code Block</h1>
4747

4848
<div class="cs-panel-section">
4949
<h3 class="cs-panel-heading" id="code-block">Code Block Overview</h3>
50-
<figure class="cs-screenshot"><img src="https://andrewbaker.ninja/wp-content/uploads/2026/03/panel-code-block-1.jpg" alt="Code Block Overview" /></figure>
50+
<figure class="cs-screenshot"><img src="https://andrewbaker.ninja/wp-content/uploads/2026/03/panel-code-block-3.jpg" alt="Code Block Overview" /></figure>
5151
<div class="cs-panel-body">
52-
<p>The <strong>CloudScale Code Block</strong> is a Gutenberg block and shortcode for displaying syntax-highlighted code in your posts and pages.</p>
52+
<p>The <strong>CloudScale Code Block</strong> is a registered Gutenberg block (<code>cloudscale/code</code>) and a <code>[cs_code]</code> shortcode for displaying syntax-highlighted code in WordPress posts and pages. Syntax highlighting is powered by <strong>highlight.js 11.11.1</strong> loaded from the cdnjs CDN, supporting over 190 languages with auto-detection.</p>
53+
<p><strong>Block and shortcode usage:</strong></p>
5354
<ul>
54-
<li><strong>Auto language detection</strong> — the plugin detects the programming language from the code content and applies appropriate syntax highlighting automatically.</li>
55-
<li><strong>Manual language selection</strong> — override the auto-detected language from the block toolbar dropdown.</li>
56-
<li><strong>Copy to clipboard</strong> — a copy button appears on hover, letting readers copy the full code snippet with one click.</li>
57-
<li><strong>Dark / Light mode toggle</strong> — readers can switch the code block theme between dark and light to match their preference. The setting is remembered via localStorage.</li>
58-
<li><strong>Line numbers</strong> — optionally display line numbers alongside the code.</li>
59-
<li><strong>Shortcode usage:</strong> <code>[cs_code lang="php"]your code here[/cs_code]</code></li>
60-
</ul></div>
55+
<li><strong>Gutenberg block</strong> — search for "CloudScale Code Block" in the block inserter (<kbd>/code</kbd>). Language, theme override, title, and line numbers are all configurable in the block sidebar panel.</li>
56+
<li><strong>Shortcode:</strong> <code>[cs_code lang="php" title="functions.php"]your code here[/cs_code]</code>. Supported attributes: <code>lang</code> (any highlight.js language alias), <code>title</code> (displayed as a filename label above the block), <code>theme</code> (overrides the site-wide theme for this block).</li>
57+
</ul>
58+
<p><strong>Features:</strong></p>
59+
<ul>
60+
<li><strong>Auto language detection</strong> — highlight.js analyses the code content and selects the most likely language. Accuracy is high for common languages (PHP, JavaScript, Python, SQL, Bash) but lower for short snippets. Override manually via the block sidebar when detection is wrong.</li>
61+
<li><strong>14 colour themes</strong> — Atom One (default), GitHub, Monokai, Nord, Dracula, Tokyo Night, VS 2015, VS Code, Stack Overflow, Night Owl, Gruvbox, Solarized, Panda, Shades of Purple. Each theme loads a dark and light variant; the toggle button switches between them. The selection is stored in <code>localStorage</code> per browser, so each reader's preference persists across page loads.</li>
62+
<li><strong>Copy to clipboard</strong> — uses the Clipboard API (<code>navigator.clipboard.writeText()</code>) with a fallback to <code>document.execCommand('copy')</code> for older browsers.</li>
63+
<li><strong>Line numbers</strong> — toggle per block. Line numbers are rendered via CSS counter to avoid polluting the copied text when a reader clicks Copy.</li>
64+
</ul>
65+
<p><strong>Requirements:</strong> WordPress 6.0+, PHP 7.4+. The block editor script uses <code>@wordpress/blocks</code> API version available in WordPress 5.8+, but full sidebar panel support requires 6.0.</p></div>
6166
</div>
6267
<hr class="cs-divider"/>
6368

6469
<div class="cs-panel-section">
6570
<h3 class="cs-panel-heading" id="sql-tool">SQL Query Tool</h3>
66-
<figure class="cs-screenshot"><img src="https://andrewbaker.ninja/wp-content/uploads/2026/03/panel-sql-tool-1.jpg" alt="SQL Query Tool" /></figure>
71+
<figure class="cs-screenshot"><img src="https://andrewbaker.ninja/wp-content/uploads/2026/03/panel-sql-tool-3.jpg" alt="SQL Query Tool" /></figure>
6772
<div class="cs-panel-body">
68-
<p>The <strong>SQL Query Tool</strong> lets you run read-only SQL SELECT queries against your WordPress database directly from the admin — without needing phpMyAdmin or SSH access.</p>
73+
<p>The <strong>SQL Query Tool</strong> lets WordPress administrators run read-only SELECT queries against the live database from within wp-admin — without needing phpMyAdmin, Adminer, or SSH access. Results are displayed in a paginated table with column headers and query execution time.</p>
74+
<p><strong>Security model:</strong></p>
75+
<ul>
76+
<li>Access is restricted to users with the <code>manage_options</code> capability (Administrators only). All AJAX handlers verify a nonce generated with the action <code>cs_code_migrate_action</code>.</li>
77+
<li>Every query is validated by <code>is_safe_query()</code> before execution. This function: strips all block comments (including MySQL optimizer hint syntax <code>/*!...*/</code>) and line comments (<code>--</code> and <code>#</code>), rejects any query containing a semicolon (prevents statement stacking), blocks <code>INTO OUTFILE</code>, <code>INTO DUMPFILE</code>, and <code>LOAD_FILE</code> clauses, and only allows queries starting with <code>SELECT</code>, <code>SHOW</code>, <code>DESCRIBE</code>, <code>DESC</code>, or <code>EXPLAIN</code>.</li>
78+
<li>Queries are executed via <code>$wpdb->get_results()</code> with <code>suppress_errors(true)</code>. Any MySQL error is caught and displayed without exposing the full stack trace.</li>
79+
</ul>
80+
<p><strong>14 built-in quick queries</strong> organised into four groups:</p>
6981
<ul>
70-
<li>Only <code>SELECT</code> statements are allowed — the tool blocks any query that could modify data (<code>INSERT</code>, <code>UPDATE</code>, <code>DELETE</code>, <code>DROP</code>, etc.).</li>
71-
<li>Results are displayed in a formatted table with column headers.</li>
72-
<li>Row count and query execution time are shown below the results.</li>
73-
<li>Useful for quick data lookups, verifying plugin data, and debugging without leaving WordPress admin.</li>
82+
<li><em>Health &amp; Diagnostics</em>: database health check, site identity options, table sizes and row counts.</li>
83+
<li><em>Content Summary</em>: posts by type and status, site stats, latest 20 published posts.</li>
84+
<li><em>Bloat &amp; Cleanup</em>: orphaned postmeta, expired transients, revisions/drafts/trash, largest autoloaded options.</li>
85+
<li><em>URL &amp; Migration Helpers</em>: HTTP references, posts with HTTP GUIDs, old IP references, posts missing meta descriptions.</li>
7486
</ul>
75-
<p><strong>Note:</strong> this tool is only accessible to WordPress administrators.</p></div>
87+
<p><strong>Keyboard shortcuts:</strong> <kbd>Enter</kbd> or <kbd>Ctrl+Enter</kbd> runs the query. <kbd>Shift+Enter</kbd> inserts a newline.</p></div>
7688
</div>
7789
<hr class="cs-divider"/>
7890

7991
<div class="cs-panel-section">
8092
<h3 class="cs-panel-heading" id="migrator">Code Block Migrator</h3>
81-
<figure class="cs-screenshot"><img src="https://andrewbaker.ninja/wp-content/uploads/2026/03/panel-migrator-1.jpg" alt="Code Block Migrator" /></figure>
93+
<figure class="cs-screenshot"><img src="https://andrewbaker.ninja/wp-content/uploads/2026/03/panel-migrator-3.jpg" alt="Code Block Migrator" /></figure>
8294
<div class="cs-panel-body">
83-
<p>The <strong>Code Block Migrator</strong> converts code blocks from other WordPress plugins (such as Crayon Syntax Highlighter, SyntaxHighlighter Evolved, and others) to CloudScale Code Blocks in one operation.</p>
95+
<p>The <strong>Code Block Migrator</strong> converts legacy code block shortcodes and HTML from other WordPress syntax highlighting plugins to CloudScale Code Blocks in a single batch operation — without manual copy-paste or post-by-post editing.</p>
96+
<p><strong>Supported source formats:</strong></p>
8497
<ul>
85-
<li><strong>Scan</strong> — finds all posts and pages containing shortcodes or HTML from supported legacy plugins.</li>
86-
<li><strong>Preview</strong> — shows what will be converted before making any changes.</li>
87-
<li><strong>Convert</strong> — replaces the old shortcodes/HTML with <code>[cs_code]</code> shortcodes, preserving the code content and language attribute where possible.</li>
98+
<li>WordPress core <code><!-- wp:code --></code> blocks — preserves language class attributes where present.</li>
99+
<li>WordPress core <code><!-- wp:preformatted --></code> blocks.</li>
100+
<li><code><!-- wp:code-syntax-block/code --></code> blocks from Code Syntax Block plugin.</li>
101+
<li>Legacy <code>[code]</code>, <code>[sourcecode]</code>, and similar shortcodes — language attribute is preserved if present.</li>
88102
</ul>
89-
<p>Always take a backup before running the migrator.</p></div>
103+
<p><strong>Migration workflow:</strong></p>
104+
<ol>
105+
<li><strong>Scan</strong> — queries <code>wp_posts</code> for all posts and pages whose <code>post_content</code> contains a <code>LIKE</code> match on the supported block comment and shortcode patterns. Results are displayed as a list with post title, status, date, and block count.</li>
106+
<li><strong>Preview</strong> — for each post, shows a before/after diff of the exact content changes that will be made. No database writes occur at this stage.</li>
107+
<li><strong>Migrate single</strong> — converts one post at a time. Calls <code>$wpdb->update()</code> to write the converted <code>post_content</code> and immediately flushes the post cache with <code>clean_post_cache()</code>.</li>
108+
<li><strong>Migrate all</strong> — processes every remaining post in a single AJAX request. For large sites (&gt;500 posts), run this during low-traffic periods as it holds a series of database write locks.</li>
109+
</ol>
110+
<p><strong>Always take a backup before running the migrator.</strong> The conversion modifies <code>post_content</code> directly in the database. If the output is not what you expected, restore from backup — there is no undo button.</p></div>
90111
</div>
91112
<hr class="cs-divider"/>
92113
</div>

0 commit comments

Comments
 (0)