How to maintain this documentation

This repository is a living demo of the customer-docs workflow. Use it as a reference when setting up documentation for your own Shopify app.

The portal reads everything from the docs/ folder, builds navigation automatically, and publishes after a GitHub Actions dispatch. The sections below explain each building block.

Repository structure

Keep all documentation under docs/ at the repository root:

docs/
├── app.json              ← portal metadata (name, description, store link)
├── img/                  ← images and app icon
│   ├── icon.png          ← shown on the portal home page
│   └── example.png
├── de/                   ← German pages (same file names as en/)
│   ├── 01_index.md
│   ├── 02_setup_guide.md
│   └── ...
└── en/                   ← English pages
    ├── 01_index.md
    ├── 02_setup_guide.md
    └── ...

Each language folder must contain the same set of files. If a page exists in English, add the German counterpart (and vice versa).

Portal metadata: app.json

File: docs/app.json

This file controls how your app appears on the portal home page — not inside the documentation itself.

Field	Purpose
name	App title on the portal tile (English default)
description	Short teaser text under the title
storeUrl	Link to your Shopify App Store listing
i18n.de.name	German app title
i18n.de.description	German teaser text

Example (from this repo):

{
  "name": "Customer Docs Demo",
  "storeUrl": "https://apps.shopify.com/customer-docs-demo-repo",
  "description": "Example repository that shows how to structure, translate, and publish app documentation.",
  "i18n": {
    "de": {
      "name": "Customer Docs Demo",
      "description": "Beispiel-Repository zur Struktur, Übersetzung und Veröffentlichung von App-Dokumentation."
    }
  }
}

Place your app icon at docs/img/icon.png. The portal picks it up automatically.

Sorting and file names

Navigation order is controlled by a numeric prefix at the start of each file name:

NN_topic.md
│  └─ descriptive slug (for humans in Git)
└─ sort position (01, 02, 03 …)

File	Position in nav
01_index.md	1 — home / start page
02_setup_guide.md	2
03_user_guide.md	3
…	…

Tips:

• Use two digits (01, not 1) so files sort correctly in Git and your editor.
• To insert a page between existing ones, pick a number in between or renumber neighbours.
• To remove a page, delete the file in both language folders.

The index page and slug

Only the index page (01_index.md) needs YAML frontmatter at the top:

---
slug: /customer-docs-demo-repo/
---

Use slug: /customer-docs-demo-repo/ so the index is served at /docs/<app-id>/ in the portal. The app id must still match image paths and the GitHub workflow (see below). All other pages start directly with an # heading.

Headings and page structure

Markdown	Role
# Title	One per page — becomes the page title and nav label
## Section	Major sections; appear as in-page anchors
### Subsection	Optional; use for detail within a section

Keep titles short and merchant-friendly. Avoid stacking multiple # headings on one page.

Translations (DE / EN)

Documentation lives in parallel folders:

• docs/en/ — English (default)
• docs/de/ — German

Rules of thumb:

1. Same file names in both folders (02_setup_guide.md in en/ and de/).
2. Same heading structure — matching # and ## levels so navigation stays aligned.
3. Translate content, not file names or image paths.
4. Portal-only strings (app.json name/description) go into the i18n block.

Switch language in the portal UI; both versions are built from the same repository.

Add a new page

1. Pick the next free number (this repo currently goes up to 11).
2. Create docs/en/NN_your_topic.md with an # title and content.
3. Create docs/de/NN_your_topic.md with the same structure, translated.
4. Commit and trigger the docs workflow (see Publish changes).
5. Verify both languages in the portal.

Pages 09–11 in this repo are optional content examples (images, lists, formatting).

Images

1. Save files in docs/img/.
2. Reference them with an absolute path that includes your app id:

![Alt text describing the image](/img/customer-docs-demo-repo/example.png)

3. Always write meaningful alt text — it helps accessibility and appears when an image fails to load.

See Images in documentation for a dedicated image walkthrough, and pages 09–11 for pages with multiple screenshots.

App id must match everywhere:

Location	Example value
01_index.md frontmatter	slug: /customer-docs-demo-repo/
Image paths	/img/customer-docs-demo-repo/…
.github/workflows/docs-dispatch.yml	"app_name": "customer-docs-demo-repo"

Publish changes

After editing files under docs/:

1. Commit and push to your repository.
2. Run the Trigger Docs Update workflow (.github/workflows/docs-dispatch.yml) via Actions → Run workflow, or enable the push trigger for automatic updates.
3. The workflow sends an update-docs event to the central docs portal, which rebuilds and deploys your app docs.

Required secret: DOCS_PORTAL_PAT with write access to the portal repository.

Example pages in this repo

#	Topic	What it demonstrates
01	This page	Structure, app.json, sorting, translations, publishing
02	Setup Guide	Simple numbered steps
03	Images	Embedding screenshots and icons
04	Uninstall	Required Shopify uninstall instructions
05	FAQ	Question-and-answer format
06	Troubleshooting	Problem / solution sections
07	Pricing	Plan comparison headings
08	Legal	EULA, terms, privacy placeholders
09	Demo Overview	Long-form text + two images
10	Demo Features	Bullet lists and step sequences
11	Demo Gallery	Links, code, and tables

Quick checklist

Before you merge documentation changes:

• New pages exist in both de/ and en/
• File names use the correct numeric prefix
• Index slug and image paths use the correct app id
• app.json updated if portal tile text changed
• Images added to docs/img/ and referenced with alt text
• Docs workflow triggered after push

Questions about this demo? Contact your Shopify app support team.