Gutenberg Importer Tricks

Docspress borrows a few practical ideas from the Block Editor Handbook importer used by WordPress/gutenberg, but packages them as a reusable GitHub Action.

This page demonstrates the features that came from that comparison.

Local Markdown links

These links are written as normal Markdown file references:

• Getting Started
• Markdown Features
• Action Inputs
• Root docs page

Docspress rewrites them to the generated WordPress page URLs during sync.

Manifest mode

The demo workflow uses docs/docspress.manifest.json so the published page structure is explicit:

{
  "pages": [
    {
      "id": "gutenberg-importer-tricks",
      "title": "Gutenberg Importer Tricks",
      "slug": "gutenberg-importer-tricks",
      "parent": "guides",
      "markdown_source": "guides/gutenberg-importer-tricks.md"
    }
  ]
}

Entries without markdown_source, such as guides and reference, become managed placeholder parent pages.

Redirect map

The demo also includes docs/redirects.json:

{
  "redirects": {
    "guides/old-markdown-features": "guides/markdown-features",
    "reference/old-action-options": "reference/action-inputs",
    "legacy/gutenberg-importer-tricks": "guides/gutenberg-importer-tricks"
  }
}

On WordPress.com these become managed moved-page placeholders. They are useful for readers and search engines, but they are not server-level 301 redirects.

Code tabs

The Gutenberg Handbook uses code tabs for examples that need two versions. Docspress supports the same authoring pattern:

import { Button } from "@wordpress/components";


export function SaveButton() {
return <Button variant="primary">Save docs</Button>;
}

const { Button } = wp.components;




function SaveButton() {
return wp.element.createElement(
Button,
{ variant: "primary" },
"Save docs"
);
}

The synced output is a Gutenberg HTML block with code-tabs, code-tab, and code-tab-block markup.

Edit links

The workflow enables:

edit-link: true
edit-link-text: Improve this page on GitHub
github-repository: f/docspress-demo
github-ref: main

Markdown-backed pages get an edit link appended at the bottom. Generated placeholder and redirect pages do not, because they do not have a Markdown source file.

Workflow inputs

The demo workflow turns the borrowed behavior on with these inputs:

manifest-file: docs/docspress.manifest.json
redirects-file: docs/redirects.json
rewrite-links: true
edit-link: true

Improve this page on GitHub