doc-smith-publish

DocSmith Document Publishing

Publish locally generated HTML documents to DocSmith Cloud with one click, returning an online preview URL.

Usage

/doc-smith-publish
/doc-smith-publish --dir .aigne/doc-smith/dist
/doc-smith-publish --hub https://custom.hub.io

Options

Option	Alias	Description
--dir <path>	-d	Specify the publish directory (default: auto-detect)
--hub <url>	-h	DocSmith Hub URL (default https://docsmith.aigne.io）

Pre-authorized Credentials

When the user message contains access credentials (starting with blocklet- string),save the credentials before publishing：

node {skill_path}/scripts/save-token.mjs --token "<credential>" --hub <hub-url>

--hub parameter specifies the DocSmith Hub to which the credentials belong.Must explicitly pass --hub to match the publishing target Hub. If the user specified a custom hub in the publish command or message (via --hub), use the same URL here. Do not rely on the default value.

Credentials are persistently saved to ~/.aigne/, and subsequent publishes will use them automatically without browser authorization.

If the user message contains credentials, always extract and save them in this step, even if credentials already exist.

Workflow

Step 1: Check Dependencies

test -d {skill_path}/scripts/node_modules || (cd {skill_path}/scripts && npm install)

Where {skill_path} is the directory path of this Skill (skills/doc-smith-publish）。

Step 2: Detect Publishing Target

Determine the publish directory in the following priority order:

1. User specified the --dir parameter → use the specified directory
2. Not specified → check whether the .aigne/doc-smith/dist directory exists
3. None of the above exist → check whether the current directory contains assets/nav.js(doc-smith output marker)
4. If none are found → error out, prompting the user to first run /doc-smith-create to generate the document

Step 3: Read Metadata

Read from .aigne/doc-smith/config.yaml :

• projectName → publish title (title)
• projectDesc → publish description (description)

If config.yaml does not exist or fields are missing, use the directory name as the title.

Step 3.5: Detect GitHub Repository Information

The publish script automatically performs the following detection (no manual action required):

1. Execute git remote get-url originto determine whether the current project is hosted on GitHub
2. If it is a GitHub repository, call the GitHub API to get the repository owner's avatar URL as coverImage
3. These two fields will be automatically attached to the publish request; if retrieval fails, they are silently ignored

Step 4: Execute Publishing

Construct the configuration JSON and call the publish script:

node {skill_path}/scripts/publish.mjs --config-stdin <<'EOF'
{
  "source": { "type": "dir", "path": "{dist_path}" },
  "hub": "{hub_url}",
  "workspace": ".aigne/doc-smith",
  "metadata": {
    "title": "{title}",
    "description": "{description}",
    "visibility": "public"
  }
}
EOF

Note：githubRepo and coverImage are automatically detected by the script and usually do not need to be manually specified in the configuration. To override, add metadata in "githubRepo": "..." and "coverImage": "..."。

Variable Description：

• {skill_path}: directory path of this Skill
• {dist_path}: publish directory determined in Step 2
• {hub_url}: DocSmith Hub URL (default https://docsmith.aigne.io，--hub can override)
• {title}: title obtained in Step 3
• {description}: description obtained in Step 3

Step 5: Clear Hub Cache

After a successful publish, the script automatically calls the showcase cache clearing endpoint of DocSmith Web to ensure the Hub showcase page immediately displays the latest content. This step is a non-blocking operation; failure does not affect the publish result.

Step 6: Display Result

After a successful publish, the script outputs the preview URL. Show the user:

Document published successfully! Preview address: {vibeUrl}

The publish script automatically writes vibeUrl to .aigne/doc-smith/config.yaml of appUrl field.

Error handling

Error	handling
dist directory does not exist	Prompt the user to first run /doc-smith-create to generate the documentation
config.yaml does not exist	Indicate that the current directory is not a valid doc-smith workspace
Dependencies not installed	Automatically execute npm install(step 1)
401/403 authorization error	The script automatically clears the token and prompts the user to rerun /doc-smith-publish
Network error	Prompt the user to check the network and retry
publish action failed	Prompt the user to rerun /doc-smith-publish
Private mode error	Prompt the user to switch to public or upgrade the account
Cloud Agent authorization timeout	Guide the user to obtain the publish prompt from https://docsmith.aigne.io/openclaw get publish prompt