{"id":4910,"date":"2026-01-26T01:50:59","date_gmt":"2026-01-26T06:50:59","guid":{"rendered":"https:\/\/chubes.net\/?documentation=usage-guide-2"},"modified":"2026-03-01T23:09:28","modified_gmt":"2026-03-02T04:09:28","slug":"usage-guide-2","status":"publish","type":"documentation","link":"https:\/\/chubes.net\/docs\/chubes-docs\/usage-guide-2\/","title":{"rendered":"Usage Guide"},"content":{"rendered":"<h2 class=\"wp-block-heading\">Documentation Post Type<\/h2><p>The plugin provides a <code>documentation<\/code> custom post type for creating and managing documentation.<\/p><h3 class=\"wp-block-heading\">Features<\/h3><ul class=\"wp-block-list\"><li>Gutenberg editor support<\/li><li>Markdown processing<\/li><li>Project taxonomy for organization<\/li><li>REST API access<\/li><li>Archive and single views<\/li><\/ul><h3 class=\"wp-block-heading\">Creating Documentation<\/h3><ol class=\"wp-block-list\"><li>In WordPress admin, go to Documentation &gt; Add New<\/li><li>Write your documentation content<\/li><li>Assign to appropriate project taxonomy terms<\/li><li>Publish<\/li><\/ol><h2 class=\"wp-block-heading\">Project Taxonomy<\/h2><p>Organize documentation with the <code>project<\/code> hierarchical taxonomy.<\/p><h3 class=\"wp-block-heading\">Structure<\/h3><ul class=\"wp-block-list\"><li>wordpress-plugins<\/li><li>wordpress-themes<\/li><li>discord-bots<\/li><li>php-libraries<\/li><\/ul><h3 class=\"wp-block-heading\">Usage<\/h3><p>Assign taxonomy terms to documentation posts for categorization and filtering.<\/p><h2 class=\"wp-block-heading\">REST API<\/h2><p>For exact request\/response shapes and permissions, see the <a href=\"https:\/\/chubes.net\/docs\/chubes-docs\/api-reference\/\">API Reference<\/a>.<\/p><h3 class=\"wp-block-heading\">Endpoints (Summary)<\/h3><p>All endpoints use the <code>docsync\/v1<\/code> namespace.<\/p><h4 class=\"wp-block-heading\">Documentation<\/h4><ul class=\"wp-block-list\"><li><code>GET \/wp-json\/docsync\/v1\/docs<\/code> &#8211; List documentation posts<\/li><li><code>POST \/wp-json\/docsync\/v1\/docs<\/code> &#8211; Create new documentation<\/li><li><code>GET \/wp-json\/docsync\/v1\/docs\/{id}<\/code> &#8211; Get specific documentation<\/li><li><code>PUT \/wp-json\/docsync\/v1\/docs\/{id}<\/code> &#8211; Update documentation<\/li><li><code>DELETE \/wp-json\/docsync\/v1\/docs\/{id}<\/code> &#8211; Delete documentation<\/li><\/ul><h4 class=\"wp-block-heading\">Project Taxonomy<\/h4><ul class=\"wp-block-list\"><li><code>GET \/wp-json\/docsync\/v1\/project<\/code> &#8211; List project taxonomy terms<\/li><li><code>GET \/wp-json\/docsync\/v1\/project\/tree<\/code> &#8211; Get hierarchical project tree<\/li><li><code>POST \/wp-json\/docsync\/v1\/project\/resolve<\/code> &#8211; Resolve or create taxonomy path<\/li><li><code>GET \/wp-json\/docsync\/v1\/project\/{id}<\/code> &#8211; Get specific taxonomy term<\/li><li><code>PUT \/wp-json\/docsync\/v1\/project\/{id}<\/code> &#8211; Update taxonomy term<\/li><\/ul><h4 class=\"wp-block-heading\">Sync Operations<\/h4><ul class=\"wp-block-list\"><li><code>POST \/wp-json\/docsync\/v1\/sync\/setup<\/code> &#8211; Setup project + category terms<\/li><li><code>GET \/wp-json\/docsync\/v1\/sync\/status<\/code> &#8211; Get sync status for a project<\/li><li><code>POST \/wp-json\/docsync\/v1\/sync\/doc<\/code> &#8211; Sync a single document<\/li><li><code>POST \/wp-json\/docsync\/v1\/sync\/batch<\/code> &#8211; Batch sync documents<\/li><li><code>POST \/wp-json\/docsync\/v1\/sync\/all<\/code> &#8211; Manually sync GitHub docs for all projects<\/li><li><code>POST \/wp-json\/docsync\/v1\/sync\/term\/{id}<\/code> &#8211; Manually sync GitHub docs for a term<\/li><li><code>GET \/wp-json\/docsync\/v1\/sync\/test-token<\/code> &#8211; GitHub token diagnostics<\/li><li><code>POST \/wp-json\/docsync\/v1\/sync\/test-repo<\/code> &#8211; GitHub repo diagnostics (<code>repo_url<\/code>)<\/li><\/ul><h3 class=\"wp-block-heading\">Parameters<\/h3><p>See <a href=\"https:\/\/chubes.net\/docs\/chubes-docs\/api-reference\/\">API Reference<\/a> for complete parameter documentation.<\/p><h4 class=\"wp-block-heading\">Quick Reference<\/h4><ul class=\"wp-block-list\"><li><code>per_page<\/code> &#8211; Number of results per page (default: 10)<\/li><li><code>page<\/code> &#8211; Page number for pagination<\/li><li><code>project<\/code> &#8211; Filter by project taxonomy term slug<\/li><li><code>status<\/code> &#8211; Filter by post status (publish, draft, etc.)<\/li><li><code>search<\/code> &#8211; Search term for title\/content<\/li><\/ul><h2 class=\"wp-block-heading\">Markdown Processing<\/h2><p>Documentation content supports Markdown syntax via Parsedown.<\/p><h3 class=\"wp-block-heading\">Supported Features<\/h3><ul class=\"wp-block-list\"><li>Headers (# ## ###)<\/li><li>Lists (- * numbered)<\/li><li>Code blocks (&#8220;`)<\/li><li>Links and images<\/li><li>Bold and italic text<\/li><\/ul><h2 class=\"wp-block-heading\">Sync System<\/h2><h3 class=\"wp-block-heading\">Components<\/h3><ul class=\"wp-block-list\"><li><strong>MarkdownProcessor<\/strong>: Converts Markdown to HTML with internal link resolution<\/li><li><strong>SyncManager<\/strong>: Handles external documentation synchronization and taxonomy management<\/li><li><strong>RepositoryFields<\/strong>: Manages GitHub\/WordPress.org repository metadata and install tracking<\/li><\/ul><h3 class=\"wp-block-heading\">Sync Process<\/h3><ol class=\"wp-block-list\"><li><strong>Project Setup<\/strong>: Use <code>\/sync\/setup<\/code> to create project taxonomy terms and categories<\/li><li><strong>Document Sync<\/strong>: Use <code>\/sync\/doc<\/code> or <code>\/sync\/batch<\/code> to import documentation with proper taxonomy assignment<\/li><li><strong>Content Processing<\/strong>: Markdown content is converted to HTML with internal link resolution<\/li><li><strong>Taxonomy Management<\/strong>: Automatic creation of hierarchical taxonomy terms as needed<\/li><li><strong>Metadata Updates<\/strong>: Repository information and install counts are automatically fetched and updated<\/li><\/ol><h3 class=\"wp-block-heading\">Sync Parameters<\/h3><ul class=\"wp-block-list\"><li><code>project_term_id<\/code>: ID of the project taxonomy term (required)<\/li><li><code>subpath<\/code>: Hierarchical path within the project as array (e.g., [&quot;api&quot;, &quot;endpoints&quot;])<\/li><li><code>source_file<\/code>: Original source file path for reference (required)<\/li><li><code>title<\/code>: Documentation title (required)<\/li><li><code>content<\/code>: Markdown content (required)<\/li><li><code>filesize<\/code>: Size of source file in bytes (required)<\/li><li><code>timestamp<\/code>: ISO 8601 timestamp of last modification (required)<\/li><li><code>excerpt<\/code>: Brief description<\/li><li><code>force<\/code>: Override existing content (boolean, default: false)<\/li><\/ul><h2 class=\"wp-block-heading\">Install Tracking<\/h2><p>The plugin tracks install counts for project terms that have a WordPress.org URL configured (returned as <code>meta.installs<\/code> on <code>GET \/project\/{id}<\/code>).<\/p><h2 class=\"wp-block-heading\">Templates<\/h2><p>The plugin provides custom templates for documentation display:<\/p><ul class=\"wp-block-list\"><li>Archive template for documentation lists<\/li><li>Single template for individual docs<\/li><li>Codebase card components<\/li><li>Related posts functionality<\/li><\/ul><h2 class=\"wp-block-heading\">Development<\/h2><h3 class=\"wp-block-heading\">Hooks and Filters<\/h3><p>This plugin uses standard WordPress hooks internally. Public hooks\/filters are not currently documented here; rely on the codebase when extending.<\/p><h3 class=\"wp-block-heading\">Components<\/h3><ul class=\"wp-block-list\"><li>Api\/Controllers\/DocsController.php &#8211; REST API handling<\/li><li>Fields\/ &#8211; Metadata management<\/li><li>Sync\/ &#8211; Synchronization logic<\/li><li>Templates\/ &#8211; Display components<\/li><\/ul><h2 class=\"wp-block-heading\">Troubleshooting<\/h2><h3 class=\"wp-block-heading\">Common Issues<\/h3><p><strong>Sync fails with &quot;Project term not found&quot;<\/strong><\/p><ul class=\"wp-block-list\"><li>Ensure you&#8217;ve called <code>\/sync\/setup<\/code> first to create the project taxonomy terms<\/li><li>Verify the <code>project_term_id<\/code> matches the ID returned from setup<\/li><li>Check that the project term exists in the project taxonomy<\/li><\/ul><p><strong>Content not updating<\/strong><\/p><ul class=\"wp-block-list\"><li>Set <code>force: true<\/code> in your sync request to override existing content<\/li><li>Verify the <code>timestamp<\/code> parameter is newer than the existing document&#8217;s timestamp<\/li><li>Check if the document hash has actually changed<\/li><\/ul><p><strong>Invalid subpath errors<\/strong><\/p><ul class=\"wp-block-list\"><li>Ensure <code>subpath<\/code> is an array of strings, not a single string<\/li><li>Avoid special characters in subpath segments<\/li><li>Keep subpath hierarchies shallow (max 3-4 levels)<\/li><\/ul><p><strong>API authentication errors<\/strong><\/p><ul class=\"wp-block-list\"><li>Ensure you&#8217;re using proper WordPress authentication (cookies or application passwords)<\/li><li>Verify user has appropriate permissions (<code>edit_posts<\/code> for <code>\/sync\/doc<\/code> and <code>\/sync\/batch<\/code>; <code>manage_options<\/code> for manual GitHub sync and diagnostics)<\/li><li>Check that the REST API is enabled on your WordPress installation<\/li><\/ul><h3 class=\"wp-block-heading\">Debug Mode<\/h3><p>Enable WordPress debug logging to troubleshoot issues:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">php<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-php\"><code class=\"language-php\">\/\/ Add to wp-config.php\ndefine(&#039;WP_DEBUG&#039;, true);\ndefine(&#039;WP_DEBUG_LOG&#039;, true);<\/code><\/pre><\/div><p>Check <code>\/wp-content\/debug.log<\/code> for detailed error information and API request logs.<\/p><h3 class=\"wp-block-heading\">Checking Sync Status<\/h3><p>Monitor sync operations:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">bash<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-bash\"><code class=\"language-bash\"># Get sync status for a project\ncurl \/wp-json\/docsync\/v1\/sync\/status?project=my-plugin\n\n# List recent documentation\ncurl \/wp-json\/docsync\/v1\/docs?project=my-plugin&amp;per_page=10<\/code><\/pre><\/div>","protected":false},"excerpt":{"rendered":"<p>Documentation Post Type The plugin provides a documentation custom post type for creating and managing documentation. Features Gutenberg editor support Markdown processing Project taxonomy for organization REST API access Archive&#8230;<\/p>\n","protected":false},"featured_media":0,"template":"","meta":{"footnotes":""},"tags":[],"project":[491],"project_type":[484],"class_list":["post-4910","documentation","type-documentation","status-publish","hentry","project-chubes-docs","project_type-wordpress-plugins"],"project_info":{"id":491,"name":"Chubes Docs","slug":"chubes-docs"},"project_type_info":{"id":484,"name":"WordPress Plugins","slug":"wordpress-plugins"},"_links":{"self":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/4910","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation"}],"about":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/types\/documentation"}],"version-history":[{"count":4,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/4910\/revisions"}],"predecessor-version":[{"id":10112,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/4910\/revisions\/10112"}],"wp:attachment":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/media?parent=4910"}],"wp:term":[{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/tags?post=4910"},{"taxonomy":"project","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/project?post=4910"},{"taxonomy":"project_type","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/project_type?post=4910"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}