From 2dca7e220e76dcc180959cfd34b79bb4a6f7e62c Mon Sep 17 00:00:00 2001 From: Fabio Lussi <198260595+itrycodinganditsbad@users.noreply.github.com> Date: Mon, 12 Oct 2026 04:05:27 +0200 Subject: [PATCH 1/8] docs: add user docs for DesignCraft Baseline user docs in docs/user/ (published at getartcraft.com/docs/designcraft), the docs-check and docs-publish workflows, and a "User docs" rule in AGENTS.md. Source notes per page: - index.md: README (intro, features, license), website crafting-apps.ts entry. - getting-started/index.md: crates/ui-egui/src/chrome.rs start_screen buttons. - getting-started/install.md: README Downloads, gh release view v0.6.0 asset list, packaging/windows/designcraft.wxs (Start Menu shortcut), launcher catalog.rs. - guides/create-a-document.md: dialogs.rs newDocument dialog, build.rs PRESETS, menus.rs UI_COMMANDS, chrome.rs start screen. - guides/open-a-file.md: apps/designcraft main.rs open_filters, engine file.rs and interchange.rs docs, lib.rs import warnings test, issue #110. - guides/place-images-and-text.md: main.rs place filters, engine file.rs file.place, dialogs.rs pdfImport, menus.rs placeWithOptions, release notes (#80). - guides/export-a-pdf.md: dialogs.rs pdf_export and apply_pdf_preset, menus.rs. - troubleshooting/app-closes-at-start.md: README graphics backend and logs, apps/designcraft/src/gpu.rs, issues #167, #192, #220, #273. - troubleshooting/get-help.md: README Logs section. - faq/is-it-free.md: README, docs/gaps.md. faq/supported-systems.md: README, release assets. faq/indesign-files.md: main.rs open filters, issues #450, #451, #110. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/docs-check.yml | 32 ++++++++++ .github/workflows/docs-publish.yml | 22 +++++++ AGENTS.md | 3 + docs/user/AGENTS.md | 64 +++++++++++++++++++ docs/user/CLAUDE.md | 1 + docs/user/faq/indesign-files.md | 14 ++++ docs/user/faq/index.md | 9 +++ docs/user/faq/is-it-free.md | 10 +++ docs/user/faq/supported-systems.md | 15 +++++ docs/user/getting-started/index.md | 14 ++++ docs/user/getting-started/install.md | 46 +++++++++++++ docs/user/guides/create-a-document.md | 41 ++++++++++++ docs/user/guides/export-a-pdf.md | 36 +++++++++++ docs/user/guides/index.md | 10 +++ docs/user/guides/open-a-file.md | 32 ++++++++++ docs/user/guides/place-images-and-text.md | 44 +++++++++++++ docs/user/index.md | 21 ++++++ .../troubleshooting/app-closes-at-start.md | 34 ++++++++++ docs/user/troubleshooting/get-help.md | 31 +++++++++ docs/user/troubleshooting/index.md | 8 +++ 20 files changed, 487 insertions(+) create mode 100644 .github/workflows/docs-check.yml create mode 100644 .github/workflows/docs-publish.yml create mode 100644 docs/user/AGENTS.md create mode 120000 docs/user/CLAUDE.md create mode 100644 docs/user/faq/indesign-files.md create mode 100644 docs/user/faq/index.md create mode 100644 docs/user/faq/is-it-free.md create mode 100644 docs/user/faq/supported-systems.md create mode 100644 docs/user/getting-started/index.md create mode 100644 docs/user/getting-started/install.md create mode 100644 docs/user/guides/create-a-document.md create mode 100644 docs/user/guides/export-a-pdf.md create mode 100644 docs/user/guides/index.md create mode 100644 docs/user/guides/open-a-file.md create mode 100644 docs/user/guides/place-images-and-text.md create mode 100644 docs/user/index.md create mode 100644 docs/user/troubleshooting/app-closes-at-start.md create mode 100644 docs/user/troubleshooting/get-help.md create mode 100644 docs/user/troubleshooting/index.md diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml new file mode 100644 index 000000000..b89a00a88 --- /dev/null +++ b/.github/workflows/docs-check.yml @@ -0,0 +1,32 @@ +name: docs-check + +on: + pull_request: + paths: ["docs/user/**"] + push: + branches: [main] + paths: ["docs/user/**"] + +permissions: + contents: read + +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + - name: Download the shared docs checker + id: fetch + run: | + url=https://raw.githubusercontent.com/storytold/artcraft-services/main/frontend/apps/artcraft-website-next/scripts/docs/core.mjs + if curl -fsSL "$url" -o "$RUNNER_TEMP/docs-core.mjs"; then + echo "ok=1" >> "$GITHUB_OUTPUT" + else + echo "::warning::The docs checker is not published yet; skipping." + fi + - name: Check docs/user + if: steps.fetch.outputs.ok == '1' + run: node "$RUNNER_TEMP/docs-core.mjs" docs/user diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml new file mode 100644 index 000000000..df4a412cc --- /dev/null +++ b/.github/workflows/docs-publish.yml @@ -0,0 +1,22 @@ +name: docs-publish + +on: + push: + branches: [main] + paths: ["docs/user/**"] + +permissions: {} + +jobs: + rebuild: + runs-on: ubuntu-latest + steps: + - name: Rebuild getartcraft.com + env: + HOOK: ${{ secrets.DOCS_BUILD_HOOK }} + run: | + if [ -z "$HOOK" ]; then + echo "DOCS_BUILD_HOOK is not set; the nightly website build will pick this up." + exit 0 + fi + curl -fsS -X POST -d '{}' "$HOOK?trigger_title=docs%20update%20from%20$GITHUB_REPOSITORY" diff --git a/AGENTS.md b/AGENTS.md index 65693656c..23ca7a099 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,6 +40,9 @@ People trust DesignCraft with their layouts; a crash loses their work. **This ou ## Roadmap `ROADMAP.md` (committed) is the one-page summary: stage, headline numbers, dimensions, languages, progress log. It follows craftrules' [`standards/progress-docs.md`](https://github.com/storytold/craftrules/blob/main/standards/progress-docs.md). Details: `docs/target-app-parity.md` (assessment), `docs/gaps.md` (ranked work list: pick from the top), `docs/roadmap.md` (milestones, current focus), `docs/parity-checklist.md` (presence checklist, `cargo xtask parity`), and the typography, file-format, UI, hardware and localization parity docs in `docs/`. When work lands, update the affected docs and their status lines, delete or shrink the closed gap, and add a progress-log line to ROADMAP.md. +## User docs +User docs live in `docs/user/` and are published at https://getartcraft.com/docs/designcraft. If a change alters something a user sees or does (menu or dialog labels, install, file formats, errors), update the matching page in `docs/user/` in the same PR, or add one. Rules: `docs/user/AGENTS.md`. + ## Contributor credits (About window) - About ▸ Contributors/Models are compiled into the binary from `contributors/contributors.json` diff --git a/docs/user/AGENTS.md b/docs/user/AGENTS.md new file mode 100644 index 000000000..2edbd117c --- /dev/null +++ b/docs/user/AGENTS.md @@ -0,0 +1,64 @@ +# User docs: rules for agents and contributors + +Everything in this folder (except this file, CLAUDE.md and README.md) is published at +https://getartcraft.com/docs/designcraft. The file path is the URL: +`troubleshooting/app-closes-at-start.md` → `/docs/designcraft/troubleshooting/app-closes-at-start`. +Renaming a file breaks links, so add the old path to `redirect_from` when you rename. + +## Who reads this + +Artists and designers using DesignCraft, Discord mods answering them, and AI assistants looking things up for +either. Write for an artist, not a developer. + +## Page rules + +- One question or problem per page. Lead with the answer or the fix in the first two lines. +- Plain words, short sentences, numbered steps for anything the reader does. +- Start the body at `##`. The page title comes from frontmatter. +- Link to other pages instead of repeating them. Use relative links to the `.md` file: + `[Install DesignCraft](../getting-started/install.md)`. +- No marketing copy, no "simply", no claims you have not checked in the code or a release. +- Call the product "DesignCraft", as the app, its downloads and getartcraft.com do. +- Name UI labels exactly as the app shows them, in **bold**. +- Document Windows 11 only. Do not name older Windows versions. +- Troubleshooting pages: `## Symptoms`, `## Fix`, `## Why this happens` (optional), + `## Still stuck?` (link the issue tracker or Discord). + +## Frontmatter + + --- + title: App closes right after it starts + description: One sentence for search results, link previews and AI summaries. + order: 10 # optional, sorts within the folder (lower first) + verified: 0.6.0 # optional, app version you last checked this page against + redirect_from: [old/path] # optional, old URLs (relative to /docs/designcraft) + --- + +Only `key: value` and `key: [a, b]` lines work. Quote values that start with a quote or contain ` #`. + +Set `verified` to the workspace `version` in the root `Cargo.toml` whenever you check a +page against the current code. + +## Folders + +- `getting-started/` install and first run +- `guides/` how to do one thing +- `troubleshooting/` symptom → fix +- `faq/` short answers +- `reference/` lists and settings + +A folder's `index.md` names the folder in the sidebar. Files or folders starting with `_` are +drafts and are not published. + +## Check before you push + + curl -fsSL https://raw.githubusercontent.com/storytold/artcraft-services/main/frontend/apps/artcraft-website-next/scripts/docs/core.mjs -o /tmp/docs-core.mjs + node /tmp/docs-core.mjs docs/user + +CI runs the same check on every PR that touches `docs/user/`. + +## Support PRs + +Pages written to answer a user question come in as PRs titled `docs(support): `. +Review them like code: check every claim against the source. Questions and bugs go to +https://github.com/storytold/designcraft/issues. diff --git a/docs/user/CLAUDE.md b/docs/user/CLAUDE.md new file mode 120000 index 000000000..47dc3e3d8 --- /dev/null +++ b/docs/user/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/docs/user/faq/indesign-files.md b/docs/user/faq/indesign-files.md new file mode 100644 index 000000000..cac429f37 --- /dev/null +++ b/docs/user/faq/indesign-files.md @@ -0,0 +1,14 @@ +--- +title: Can DesignCraft open InDesign files? +description: DesignCraft opens and exports InDesign Markup (.idml) files. The Open dialog does not list InDesign's own .indd format. +order: 30 +verified: 0.6.0 +--- + +Yes for IDML, the InDesign Markup format. DesignCraft can open `.idml` files and export them with **File**, then **Export IDML…**. + +The **Open…** dialog lists `.designcraft` and `.idml` files only, so it does not offer InDesign's own `.indd` files. See [Open a DesignCraft or InDesign (IDML) file](../guides/open-a-file.md). + +IDML import is not complete. Open issues in the tracker report that custom text-wrap boundaries ([#451](https://github.com/storytold/designcraft/issues/451)) and saved image clipping paths ([#450](https://github.com/storytold/designcraft/issues/450)) are lost when importing IDML, and that bullets and numbers in lists show as missing-font magenta in some templates ([#110](https://github.com/storytold/designcraft/issues/110)). Check your layout after importing. + +DesignCraft can also export PDF (including PDF/X-4 and PDF/A-2b), PNG and EPUB. See [Export a PDF](../guides/export-a-pdf.md). diff --git a/docs/user/faq/index.md b/docs/user/faq/index.md new file mode 100644 index 000000000..2fefa867b --- /dev/null +++ b/docs/user/faq/index.md @@ -0,0 +1,9 @@ +--- +title: FAQ +description: Short answers about DesignCraft's price, platforms and file formats. +order: 40 +--- + +- [Is DesignCraft free?](is-it-free.md) +- [Which systems does DesignCraft run on?](supported-systems.md) +- [Can DesignCraft open InDesign files?](indesign-files.md) diff --git a/docs/user/faq/is-it-free.md b/docs/user/faq/is-it-free.md new file mode 100644 index 000000000..bfa404b8d --- /dev/null +++ b/docs/user/faq/is-it-free.md @@ -0,0 +1,10 @@ +--- +title: Is DesignCraft free? +description: DesignCraft is free and open source, with no subscription, licence server or telemetry. +order: 10 +verified: 0.6.0 +--- + +Yes. DesignCraft is free. It has no subscription, no licence server and no telemetry. + +The code is open source under your choice of the [MIT](https://github.com/storytold/designcraft/blob/main/LICENSE-MIT) or [Apache-2.0](https://github.com/storytold/designcraft/blob/main/LICENSE-APACHE) licence. DesignCraft is in pre-alpha, so some InDesign features are not there yet. The list of known gaps is in [docs/gaps.md](https://github.com/storytold/designcraft/blob/main/docs/gaps.md) in the repository. diff --git a/docs/user/faq/supported-systems.md b/docs/user/faq/supported-systems.md new file mode 100644 index 000000000..cd118b1b4 --- /dev/null +++ b/docs/user/faq/supported-systems.md @@ -0,0 +1,15 @@ +--- +title: Which systems does DesignCraft run on? +description: DesignCraft runs on Windows 11, macOS and Linux, and in a web browser. +order: 20 +verified: 0.6.0 +--- + +DesignCraft runs on Windows, macOS and Linux, and in a modern web browser. The release also has builds for FreeBSD. + +- **Windows 11**: x64, arm64 and x86 installers, plus portable zips. +- **macOS**: one universal build for Apple silicon and Intel. +- **Linux**: x86_64 and aarch64 as AppImage, Flatpak, `.deb`, `.rpm` or tarball, and a RISC-V tarball. +- **Web**: a static site you host yourself (`designcraft-web-.zip`). It runs on WebGPU and falls back to WebGL2. The web build has no control channel, and Save and Export download the file. + +All files are on the [latest release](https://github.com/storytold/designcraft/releases/latest). See [Install DesignCraft](../getting-started/install.md) for steps. diff --git a/docs/user/getting-started/index.md b/docs/user/getting-started/index.md new file mode 100644 index 000000000..1cde0866a --- /dev/null +++ b/docs/user/getting-started/index.md @@ -0,0 +1,14 @@ +--- +title: Get started +description: Install DesignCraft, then open the sample magazine or start a new document. +order: 10 +verified: 0.6.0 +--- + +Install DesignCraft first, then start a document. + +1. [Install DesignCraft](install.md) on Windows 11, macOS or Linux. +2. Open DesignCraft. The start screen has three buttons: **New file**, **Open** and **Open sample magazine**. +3. Click **Open sample magazine** to see a finished layout, or follow [Create a new document](../guides/create-a-document.md) to begin your own. + +DesignCraft also runs in a web browser. See [Which systems does DesignCraft run on?](../faq/supported-systems.md). diff --git a/docs/user/getting-started/install.md b/docs/user/getting-started/install.md new file mode 100644 index 000000000..94d6e52ef --- /dev/null +++ b/docs/user/getting-started/install.md @@ -0,0 +1,46 @@ +--- +title: Install DesignCraft +description: Download DesignCraft 0.6.0 for Windows 11, macOS or Linux, or install it from ArtCraft Launcher. +order: 20 +verified: 0.6.0 +--- + +Download the file for your system from the [latest release](https://github.com/storytold/designcraft/releases/latest) and install it. In the file names, `` stands for the version number, for example `0.6.0`. The release also has `SHA256SUMS.txt`, which lists a checksum for every file. The [DesignCraft page on getartcraft.com](https://getartcraft.com/apps/designcraft) links to the download as well. + +## Windows 11 + +1. Open the [latest release](https://github.com/storytold/designcraft/releases/latest). +2. Download `designcraft--windows-x64.msi`. It fits most PCs (64-bit Intel and AMD). +3. Run the file and follow the installer. +4. Start **DesignCraft** from the Start menu. + +The release also has an `arm64` installer for ARM PCs such as Snapdragon, and an `x86` installer for 32-bit Windows. To run without installing, download `designcraft--windows-x64-portable.zip` (or the `arm64` or `x86` version), unzip it and start the program inside. The installers and executables are code-signed. + +## macOS + +1. Download `designcraft--macos-universal.dmg`. It works on Apple silicon and Intel Macs. +2. Open it and drag DesignCraft to Applications. + +The app is signed and notarized. + +## Linux + +Pick one file from the release. Replace `x86_64` with `aarch64` on ARM. + +| File | Notes | +|-------------------------------------------|----------------------------------------------------------| +| `designcraft--linux-x86_64.AppImage` | Runs anywhere. | +| `designcraft--linux-x86_64.flatpak` | Sandboxed. Install with `flatpak install --user `. | +| `designcraft--linux-x86_64.deb` | Debian and Ubuntu. | +| `designcraft--linux-x86_64.rpm` | Fedora, RHEL and openSUSE. | +| `designcraft--linux-x86_64.tar.gz` | Unpack anywhere. | + +For RISC-V there is only `designcraft--linux-riscv64.tar.gz`. It needs glibc 2.39 or newer (Ubuntu 24.04 or newer). A FreeBSD build (`designcraft--freebsd-x86_64.tar.gz`) is on the release page too. + +## Install with ArtCraft Launcher + +ArtCraft Launcher lists DesignCraft and can install and update it for you. See [ArtCraft Launcher](https://getartcraft.com/docs/craft-launcher) for how it works. + +## First run + +Open DesignCraft. You land on the start screen. Continue with [Get started](index.md). If the window closes right away, see [DesignCraft closes right after it starts](../troubleshooting/app-closes-at-start.md). diff --git a/docs/user/guides/create-a-document.md b/docs/user/guides/create-a-document.md new file mode 100644 index 000000000..4e833d8d8 --- /dev/null +++ b/docs/user/guides/create-a-document.md @@ -0,0 +1,41 @@ +--- +title: Create a new document +description: Start a new DesignCraft document from a preset or with your own page size, margins and columns. +order: 10 +verified: 0.6.0 +--- + +Choose **File**, then **New Document…** (Ctrl+N), set the page size and margins, and click **OK**. + +## Steps + +1. Open the **File** menu and choose **New Document…**. On the start screen you can click **New file** instead. +2. In the **New Document** dialog, pick a **Preset**, or leave it and type your own **Width** and **Height**. +3. Set **Pages**, and tick **Facing Pages** if you want left and right pages side by side as spreads. +4. Set **Columns** and the **Gutter** between them. +5. Set the margins: **Top**, **Bottom**, **Inside** and **Outside**. +6. Set **Bleed** if the document goes to print. +7. Tick **Primary Text Frame** if you want a text frame that fills the margins on each page. +8. Click **OK**. + +## Presets + +The **Preset** list has these page sizes: + +- Print: Letter, Legal, Tabloid, Letter - Half, A3, A4, A5, A6, B5, Business Card, Postcard. +- Web: Web 1920 × 1080, Web 1366 × 768, Web 1024 × 768. +- Mobile: Mobile 1080 × 1920, Mobile 390 × 844, Tablet 1024 × 1366. + +Choosing a print preset ticks **Facing Pages**. Web and mobile presets leave it off. + +## Quick start from the start screen + +The start screen also shows a tile for each print preset under **Start a new document**. Click a tile to make a document at that size with no dialog. + +## See a finished layout + +Click **Open sample magazine** on the start screen. It opens a magazine with a cover, styled pages, threaded columns, text wrap and swatches, which is a good way to see what DesignCraft can do. + +## Next + +Save your work with **File**, then **Save** (Ctrl+S). The first save asks where to put the file and suggests a name ending in `.designcraft`. diff --git a/docs/user/guides/export-a-pdf.md b/docs/user/guides/export-a-pdf.md new file mode 100644 index 000000000..b2ea20494 --- /dev/null +++ b/docs/user/guides/export-a-pdf.md @@ -0,0 +1,36 @@ +--- +title: Export a PDF +description: Export your DesignCraft document as a PDF for desktop printing, a print shop, screen or archive. +order: 40 +verified: 0.6.0 +--- + +Choose **File**, then **Export PDF…**, pick a **Preset**, click **OK** and name the file. + +## Steps + +1. Open the **File** menu and choose **Export PDF…**. +2. In the **Export PDF** dialog, pick a **Preset:** (see the table below). +3. Under **General**, leave **Page Range:** as `all`, or type the pages you want, for example `1-3,5`. **Spreads** is a checkbox in the same section. +4. Under **Compression**, tick or clear **Compress images**. +5. Under **Marks and Bleeds**, tick **Include document bleed**, **Crop Marks**, **Bleed Marks** or **Page Information** as your printer asks. **Weight:** and **Offset:** set the marks. +6. Under **Advanced**, pick a **Standard:** (**None**, **PDF/X-4** or **PDF/A-2b**) and decide on **Tagged PDF**. +7. Click **OK**, then choose where to save. The file name starts as your document's title with `.pdf`. + +## Presets + +Picking a preset fills in the other settings. Changing any setting by hand switches the preset to **Custom**. + +| Preset | Standard | Compress images | Crop marks | Bleed marks | +|---------------------|----------|-----------------|------------|-------------| +| Desktop Printing | None | off | off | off | +| Commercial Printing | None | on | on | on | +| Screen and Email | None | on | off | off | +| PDF/X-4 | PDF/X-4 | off | on | on | +| PDF/A-2b | PDF/A-2b | off | off | off | + +**Screen and Email** also sets the transparency flattener to low resolution, which draws pages with transparency at 72 ppi. DesignCraft remembers your last settings for next time. + +## Other exports + +The **File** menu also has **Export Page as PNG…** (Ctrl+E), **Export IDML…**, **Export EPUB…**, **Export EPUB (Fixed Layout)…**, **Export PDF (Interactive)…**, **Export HTML…**, **Export XML…**, **Export Text…** and **Print Booklet…**. diff --git a/docs/user/guides/index.md b/docs/user/guides/index.md new file mode 100644 index 000000000..6180d771e --- /dev/null +++ b/docs/user/guides/index.md @@ -0,0 +1,10 @@ +--- +title: Guides +description: Step-by-step guides for the main DesignCraft tasks. +order: 20 +--- + +- [Create a new document](create-a-document.md) +- [Open a DesignCraft or InDesign (IDML) file](open-a-file.md) +- [Place images, PDFs and text](place-images-and-text.md) +- [Export a PDF](export-a-pdf.md) diff --git a/docs/user/guides/open-a-file.md b/docs/user/guides/open-a-file.md new file mode 100644 index 000000000..e435d00ce --- /dev/null +++ b/docs/user/guides/open-a-file.md @@ -0,0 +1,32 @@ +--- +title: Open a DesignCraft or InDesign (IDML) file +description: Open a .designcraft document or an InDesign Markup (.idml) file, and what to do about missing fonts and warnings. +order: 20 +verified: 0.6.0 +--- + +Choose **File**, then **Open…** (Ctrl+O), and pick a `.designcraft` or `.idml` file. The file opens as a new document. + +## Steps + +1. Open the **File** menu and choose **Open…**. On the start screen you can click **Open** instead. +2. In the file dialog, pick a file. The dialog lists two kinds: **DesignCraft** (`.designcraft`) and **InDesign Markup (IDML)** (`.idml`). +3. Confirm the dialog. The document opens as a new document. + +## What the Open dialog accepts + +The Open dialog lists `.designcraft` and `.idml` files only. To bring an image, a PDF or a text file into a document, use [Place](place-images-and-text.md) instead. + +IDML is InDesign Markup, the exchange format InDesign can export. Linked images are read from next to the file or from its `Links` folder. If a `Document Fonts` folder sits beside the file, DesignCraft loads those fonts first. + +## Missing fonts + +Text that uses a font DesignCraft cannot find is highlighted in pink. This is the missing-font highlight. Put the font files in a `Document Fonts` folder beside the file, or install the fonts on your system, so DesignCraft can find them. + +## Import warnings + +If an IDML package is missing some of its parts, DesignCraft still opens what it can and shows an alert titled **Import Warnings** that names the missing parts. Your other open documents stay as they are. Click **OK** to close the alert. + +## Save it again + +**File**, then **Save** (Ctrl+S) writes a `.designcraft` file. To hand the layout back to InDesign, use **File**, then **Export IDML…**. diff --git a/docs/user/guides/place-images-and-text.md b/docs/user/guides/place-images-and-text.md new file mode 100644 index 000000000..b10601f5c --- /dev/null +++ b/docs/user/guides/place-images-and-text.md @@ -0,0 +1,44 @@ +--- +title: Place images, PDFs and text +description: Bring images, PDF pages, Word and plain text files into a DesignCraft document with File, Place. +order: 30 +verified: 0.6.0 +--- + +Choose **File**, then **Place…** (Ctrl+D), pick a file, and DesignCraft puts it into your document. +## Steps + +1. Open the **File** menu and choose **Place…**. +2. Pick a file. The dialog's **Graphics and text** filter covers the file types below. +3. For an image, DesignCraft places it in the selected empty frame if there is one. +4. For a text file, it goes into the insertion point, the selected frame, or a new frame. + +## File types + +| Kind | Extensions | +|----------|---------------------------------------------------------------------------------| +| Images | png, jpg, jpeg, gif, webp, tif, tiff, bmp, psd, svg | +| Vector | pdf, ai, eps | +| Text | txt, docx, rtf, md | +| Table | xlsx (placed as a table) | +| Layout | idml, designcraft (one page's objects, placed as a group) | +| Media | mp4, m4v, mov, webm, mp3, m4a, wav, ogg (placed in a media frame) | + +The same dialog has separate filters for **Graphics**, **Text (Word, RTF, plain, Excel)** and **Video and sound**. + +## Place a page of a PDF + +1. Choose **File**, then **Place…** and pick a PDF with more than one page. +2. In the **Place PDF** dialog, type the page number in **Page**. The label shows the page count. +3. Pick a box in **Crop to:**. The choices are **Crop**, **Trim**, **Bleed**, **Art** and **Media**. +4. Click **OK**. + +A PDF with one page is placed without this dialog. + +## Place Word or RTF text with your styles + +**File**, then **Place with Import Options…** (Ctrl+Shift+D) opens an **Import Options** dialog for `.docx` and `.rtf` files, where you can map the file's styles to your document's styles before the text lands. For other file types it places the file straight away. + +## If a file cannot be placed + +DesignCraft shows an alert when a file cannot be opened or placed. Ask in [Discord](https://discord.gg/artcraft) or see [Report a problem](../troubleshooting/get-help.md). diff --git a/docs/user/index.md b/docs/user/index.md new file mode 100644 index 000000000..490155458 --- /dev/null +++ b/docs/user/index.md @@ -0,0 +1,21 @@ +--- +title: DesignCraft +description: DesignCraft is a free, open-source page layout app for print and screen, an alternative to Adobe InDesign. +verified: 0.6.0 +--- + +DesignCraft is a page layout and publishing app. It is an open-source alternative to Adobe InDesign, built from scratch by the ArtCraft team. If you know InDesign's tools, menus and panels, you will find them here. + +It has spreads and parent pages, text frames that thread from one to the next, paragraph and character styles, swatches and text wrap. It opens and saves InDesign Markup (IDML) files and exports PDF, PNG and EPUB. It is free, with no subscription, licence server or telemetry. The project is in pre-alpha, so expect gaps. + +## Start here + +- [Get started](getting-started/index.md) +- [Install DesignCraft](getting-started/install.md) +- [Guides](guides/index.md) +- [Troubleshooting](troubleshooting/index.md) +- [FAQ](faq/index.md) + +## Get help + +Ask in [Discord](https://discord.gg/artcraft) or open an issue in the [issue tracker](https://github.com/storytold/designcraft/issues). Say which version and which system you use. diff --git a/docs/user/troubleshooting/app-closes-at-start.md b/docs/user/troubleshooting/app-closes-at-start.md new file mode 100644 index 000000000..791465163 --- /dev/null +++ b/docs/user/troubleshooting/app-closes-at-start.md @@ -0,0 +1,34 @@ +--- +title: DesignCraft closes right after it starts +description: On Windows, DesignCraft shows a brief spinner and then closes with no message. Update, or force the DirectX 12 graphics backend. +order: 10 +verified: 0.6.0 +--- + +If DesignCraft flashes a spinner and closes, update to the [latest release](https://github.com/storytold/designcraft/releases/latest). If it still closes, set the environment variable `WGPU_BACKEND` to `dx12` and start it again. + +## Symptoms + +- On Windows, DesignCraft opens briefly with a spinner or a quick blue circle, then closes. No error message appears. +- Windows may record a crash that names a graphics driver file such as `atio6axx.dll` (AMD) or `igvk64.dll` (Intel). +- It happens with the installer and the portable version. + +## Fix + +1. Install the [latest release](https://github.com/storytold/designcraft/releases/latest). DesignCraft remembers a start that never showed a window and tries the next graphics backend on the following start. On Windows the order is DirectX 12, Vulkan, then OpenGL, and the status bar says when it switches. A reporter who could not start 0.5.0 on Windows 11 Enterprise wrote that 0.6.0 launched without trouble. +2. If it still closes, set an environment variable named `WGPU_BACKEND` with the value `dx12`. Start DesignCraft from a shell where it is set, or add it in Windows settings for your account. People who hit this crash with an AMD graphics driver reported that DesignCraft starts with `WGPU_BACKEND=dx12`. +3. Start DesignCraft again. + +Setting `WGPU_BACKEND` also turns off the automatic fallback. Other accepted values are `vulkan` and `gl`, and a comma-separated list lets the graphics library choose among them. + +## Why this happens + +DesignCraft draws the canvas on the CPU and uses the graphics card only to show the interface. Some graphics drivers crash while the window is being set up, and a crash in a driver ends the program before DesignCraft can react. One AMD laptop's Vulkan driver crashed on the first frame, which is why DirectX 12 is the default on Windows. + +## Start the backend search over + +DesignCraft keeps its record of failed backends in a file called `gpu.json` in its settings folder, the one that holds `ui.json`, `prefs.json` and the `logs` folder (`%APPDATA%\DesignCraft\logs\` is the log folder on Windows). Delete the file to start the search again. The list also starts over after every backend has failed, and with a new DesignCraft version. + +## Still stuck? + +Send the log. See [Report a problem](get-help.md) for where it is. Or ask in [Discord](https://discord.gg/artcraft). diff --git a/docs/user/troubleshooting/get-help.md b/docs/user/troubleshooting/get-help.md new file mode 100644 index 000000000..f8f32fe67 --- /dev/null +++ b/docs/user/troubleshooting/get-help.md @@ -0,0 +1,31 @@ +--- +title: Report a problem +description: What to include and where to post when DesignCraft misbehaves or crashes. +order: 20 +verified: 0.6.0 +--- + +Post in the [issue tracker](https://github.com/storytold/designcraft/issues) or in [Discord](https://discord.gg/artcraft), and attach the log file. The log is the most useful thing you can send after a crash. + +## What to include + +- Your DesignCraft version and how you installed it (installer, portable, AppImage and so on). +- Your operating system and graphics card. +- What you did, what you expected and what happened. +- The log file `designcraft.log`. + +## Where the log is + +DesignCraft writes `logs/designcraft.log` in its settings folder, beside `ui.json` and `prefs.json`. + +| System | Log folder | +|---------|-------------------------------------------------------------------------| +| Windows | `%APPDATA%\DesignCraft\logs\` | +| macOS | `~/Library/Application Support/DesignCraft/logs/` | +| Linux | `~/.config/designcraft/logs/` (or `$XDG_CONFIG_HOME/designcraft/logs/`) | + +Each start moves the previous log to `designcraft.1.log`, and that one to `designcraft.2.log`. The log from a run that crashed survives the next start, so attach `designcraft.1.log` if you have restarted since. The file stops growing at 16 MiB. + +## More detail in the log + +Set the environment variable `RUST_LOG` to `debug` before starting DesignCraft to log more. The default is `info` for DesignCraft's own parts and `warn` for everything else. diff --git a/docs/user/troubleshooting/index.md b/docs/user/troubleshooting/index.md new file mode 100644 index 000000000..b89209a59 --- /dev/null +++ b/docs/user/troubleshooting/index.md @@ -0,0 +1,8 @@ +--- +title: Troubleshooting +description: Fixes for common DesignCraft problems. +order: 30 +--- + +- [DesignCraft closes right after it starts](app-closes-at-start.md) +- [Report a problem](get-help.md) From de28587995ad986a4c90a85fffbb2e5e2bde477a Mon Sep 17 00:00:00 2001 From: Fabio Lussi <198260595+itrycodinganditsbad@users.noreply.github.com> Date: Mon, 12 Oct 2026 04:49:31 +0200 Subject: [PATCH 2/8] docs(user): apply final review fixes Items B-DesignCraft 1-6 and consistency. Co-Authored-By: Claude Opus 5.5 --- docs/user/faq/supported-systems.md | 4 ++-- docs/user/getting-started/install.md | 20 +++++++++---------- docs/user/guides/create-a-document.md | 2 ++ docs/user/guides/export-a-pdf.md | 2 ++ docs/user/guides/open-a-file.md | 8 +++++--- docs/user/guides/place-images-and-text.md | 3 +++ .../troubleshooting/app-closes-at-start.md | 6 +++--- 7 files changed, 27 insertions(+), 18 deletions(-) diff --git a/docs/user/faq/supported-systems.md b/docs/user/faq/supported-systems.md index cd118b1b4..b6701ac7c 100644 --- a/docs/user/faq/supported-systems.md +++ b/docs/user/faq/supported-systems.md @@ -7,9 +7,9 @@ verified: 0.6.0 DesignCraft runs on Windows, macOS and Linux, and in a modern web browser. The release also has builds for FreeBSD. -- **Windows 11**: x64, arm64 and x86 installers, plus portable zips. +- **Windows 11**: x64 and arm64 installers, plus portable zips. - **macOS**: one universal build for Apple silicon and Intel. - **Linux**: x86_64 and aarch64 as AppImage, Flatpak, `.deb`, `.rpm` or tarball, and a RISC-V tarball. -- **Web**: a static site you host yourself (`designcraft-web-.zip`). It runs on WebGPU and falls back to WebGL2. The web build has no control channel, and Save and Export download the file. +- **Web**: a static site you host yourself (`designcraft-web-.zip`). It runs on WebGPU and falls back to WebGL2. The web build has no control channel, and Save and Export download the file. All files are on the [latest release](https://github.com/storytold/designcraft/releases/latest). See [Install DesignCraft](../getting-started/install.md) for steps. diff --git a/docs/user/getting-started/install.md b/docs/user/getting-started/install.md index 94d6e52ef..1344fee7f 100644 --- a/docs/user/getting-started/install.md +++ b/docs/user/getting-started/install.md @@ -5,20 +5,20 @@ order: 20 verified: 0.6.0 --- -Download the file for your system from the [latest release](https://github.com/storytold/designcraft/releases/latest) and install it. In the file names, `` stands for the version number, for example `0.6.0`. The release also has `SHA256SUMS.txt`, which lists a checksum for every file. The [DesignCraft page on getartcraft.com](https://getartcraft.com/apps/designcraft) links to the download as well. +Download the file for your system from the [latest release](https://github.com/storytold/designcraft/releases/latest) and install it. In the file names, `` stands for the version number, for example `0.6.0`. The release also has `SHA256SUMS.txt`, which lists a checksum for every file. The [DesignCraft page on getartcraft.com](https://getartcraft.com/apps/designcraft) links to the download as well. ## Windows 11 1. Open the [latest release](https://github.com/storytold/designcraft/releases/latest). -2. Download `designcraft--windows-x64.msi`. It fits most PCs (64-bit Intel and AMD). +2. Download `designcraft--windows-x64.msi`. It fits most PCs (64-bit Intel and AMD). 3. Run the file and follow the installer. 4. Start **DesignCraft** from the Start menu. -The release also has an `arm64` installer for ARM PCs such as Snapdragon, and an `x86` installer for 32-bit Windows. To run without installing, download `designcraft--windows-x64-portable.zip` (or the `arm64` or `x86` version), unzip it and start the program inside. The installers and executables are code-signed. +The release also has an `arm64` installer for ARM PCs such as Snapdragon. To run without installing, download `designcraft--windows-x64-portable.zip` (or the `arm64` version), unzip it and start the program inside. The installers and executables are code-signed. ## macOS -1. Download `designcraft--macos-universal.dmg`. It works on Apple silicon and Intel Macs. +1. Download `designcraft--macos-universal.dmg`. It works on Apple silicon and Intel Macs. 2. Open it and drag DesignCraft to Applications. The app is signed and notarized. @@ -29,13 +29,13 @@ Pick one file from the release. Replace `x86_64` with `aarch64` on ARM. | File | Notes | |-------------------------------------------|----------------------------------------------------------| -| `designcraft--linux-x86_64.AppImage` | Runs anywhere. | -| `designcraft--linux-x86_64.flatpak` | Sandboxed. Install with `flatpak install --user `. | -| `designcraft--linux-x86_64.deb` | Debian and Ubuntu. | -| `designcraft--linux-x86_64.rpm` | Fedora, RHEL and openSUSE. | -| `designcraft--linux-x86_64.tar.gz` | Unpack anywhere. | +| `designcraft--linux-x86_64.AppImage` | Runs anywhere. | +| `designcraft--linux-x86_64.flatpak` | Sandboxed. Install with `flatpak install --user `. | +| `designcraft--linux-x86_64.deb` | Debian and Ubuntu. | +| `designcraft--linux-x86_64.rpm` | Fedora, RHEL and openSUSE. | +| `designcraft--linux-x86_64.tar.gz` | Unpack anywhere. | -For RISC-V there is only `designcraft--linux-riscv64.tar.gz`. It needs glibc 2.39 or newer (Ubuntu 24.04 or newer). A FreeBSD build (`designcraft--freebsd-x86_64.tar.gz`) is on the release page too. +For RISC-V there is only `designcraft--linux-riscv64.tar.gz`. It needs glibc 2.39 or newer (Ubuntu 24.04 or newer). A FreeBSD build (`designcraft--freebsd-x86_64.tar.gz`) is on the release page too. ## Install with ArtCraft Launcher diff --git a/docs/user/guides/create-a-document.md b/docs/user/guides/create-a-document.md index 4e833d8d8..76b95ae56 100644 --- a/docs/user/guides/create-a-document.md +++ b/docs/user/guides/create-a-document.md @@ -7,6 +7,8 @@ verified: 0.6.0 Choose **File**, then **New Document…** (Ctrl+N), set the page size and margins, and click **OK**. +Shortcuts on this page use Ctrl. On macOS, use Cmd instead of Ctrl. + ## Steps 1. Open the **File** menu and choose **New Document…**. On the start screen you can click **New file** instead. diff --git a/docs/user/guides/export-a-pdf.md b/docs/user/guides/export-a-pdf.md index b2ea20494..938c5dfe2 100644 --- a/docs/user/guides/export-a-pdf.md +++ b/docs/user/guides/export-a-pdf.md @@ -7,6 +7,8 @@ verified: 0.6.0 Choose **File**, then **Export PDF…**, pick a **Preset**, click **OK** and name the file. +Shortcuts on this page use Ctrl. On macOS, use Cmd instead of Ctrl. + ## Steps 1. Open the **File** menu and choose **Export PDF…**. diff --git a/docs/user/guides/open-a-file.md b/docs/user/guides/open-a-file.md index e435d00ce..2c1568346 100644 --- a/docs/user/guides/open-a-file.md +++ b/docs/user/guides/open-a-file.md @@ -1,16 +1,18 @@ --- title: Open a DesignCraft or InDesign (IDML) file -description: Open a .designcraft document or an InDesign Markup (.idml) file, and what to do about missing fonts and warnings. +description: Open a .designcraft document or an InDesign Markup (.idml) file, and what to do about missing fonts and incomplete IDML packages. order: 20 verified: 0.6.0 --- Choose **File**, then **Open…** (Ctrl+O), and pick a `.designcraft` or `.idml` file. The file opens as a new document. +Shortcuts on this page use Ctrl. On macOS, use Cmd instead of Ctrl. + ## Steps 1. Open the **File** menu and choose **Open…**. On the start screen you can click **Open** instead. -2. In the file dialog, pick a file. The dialog lists two kinds: **DesignCraft** (`.designcraft`) and **InDesign Markup (IDML)** (`.idml`). +2. In the file dialog, pick a file. The dialog lists **DesignCraft or IDML** (both, listed first), **DesignCraft** (`.designcraft`) and **InDesign Markup (IDML)** (`.idml`). 3. Confirm the dialog. The document opens as a new document. ## What the Open dialog accepts @@ -25,7 +27,7 @@ Text that uses a font DesignCraft cannot find is highlighted in pink. This is th ## Import warnings -If an IDML package is missing some of its parts, DesignCraft still opens what it can and shows an alert titled **Import Warnings** that names the missing parts. Your other open documents stay as they are. Click **OK** to close the alert. +If an IDML package is missing some of its parts, 0.6.0 may not open it. Opening such files with an **Import Warnings** alert that names the missing parts was added after 0.6.0 and is not in a release yet. ## Save it again diff --git a/docs/user/guides/place-images-and-text.md b/docs/user/guides/place-images-and-text.md index b10601f5c..3ac9b2382 100644 --- a/docs/user/guides/place-images-and-text.md +++ b/docs/user/guides/place-images-and-text.md @@ -6,6 +6,9 @@ verified: 0.6.0 --- Choose **File**, then **Place…** (Ctrl+D), pick a file, and DesignCraft puts it into your document. + +Shortcuts on this page use Ctrl. On macOS, use Cmd instead of Ctrl. + ## Steps 1. Open the **File** menu and choose **Place…**. diff --git a/docs/user/troubleshooting/app-closes-at-start.md b/docs/user/troubleshooting/app-closes-at-start.md index 791465163..b8908fe6c 100644 --- a/docs/user/troubleshooting/app-closes-at-start.md +++ b/docs/user/troubleshooting/app-closes-at-start.md @@ -15,11 +15,11 @@ If DesignCraft flashes a spinner and closes, update to the [latest release](http ## Fix -1. Install the [latest release](https://github.com/storytold/designcraft/releases/latest). DesignCraft remembers a start that never showed a window and tries the next graphics backend on the following start. On Windows the order is DirectX 12, Vulkan, then OpenGL, and the status bar says when it switches. A reporter who could not start 0.5.0 on Windows 11 Enterprise wrote that 0.6.0 launched without trouble. -2. If it still closes, set an environment variable named `WGPU_BACKEND` with the value `dx12`. Start DesignCraft from a shell where it is set, or add it in Windows settings for your account. People who hit this crash with an AMD graphics driver reported that DesignCraft starts with `WGPU_BACKEND=dx12`. +1. Install the [latest release](https://github.com/storytold/designcraft/releases/latest). DesignCraft remembers a start that never showed a window and tries the next graphics backend on the following start. On Windows the order is DirectX 12, Vulkan, then OpenGL, and the status bar says when it switches. A reporter who could not start 0.5.0 on Windows 11 Enterprise wrote that 0.6.0 launched without trouble ([issue #273](https://github.com/storytold/designcraft/issues/273)). +2. If it still closes, set an environment variable named `WGPU_BACKEND` with the value `dx12`. Start DesignCraft from a shell where it is set, or add it in Windows settings for your account. People who hit this crash with an AMD graphics driver reported that DesignCraft starts with `WGPU_BACKEND=dx12`. `dx12` also avoids Intel's Vulkan driver (`igvk64.dll`), which crashed in [issue #192](https://github.com/storytold/designcraft/issues/192). 3. Start DesignCraft again. -Setting `WGPU_BACKEND` also turns off the automatic fallback. Other accepted values are `vulkan` and `gl`, and a comma-separated list lets the graphics library choose among them. +Setting `WGPU_BACKEND` also turns off the automatic fallback. Other accepted values are `vulkan` and `gl`, and a comma-separated list lets the graphics library choose among them. Do not pick `vulkan` on Intel graphics or `gl` on AMD graphics: those are the drivers in the crash reports. ## Why this happens From 765e28a22e3a6830f0c963866eb877014fc9937c Mon Sep 17 00:00:00 2001 From: Fabio Lussi <198260595+itrycodinganditsbad@users.noreply.github.com> Date: Mon, 12 Oct 2026 05:06:06 +0200 Subject: [PATCH 3/8] docs(user): apply final review fixes Part 1: verified = latest release tag policy in docs/user/AGENTS.md; released-pages sentence in root AGENTS.md. Part 6: re-pad Linux table. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 +- docs/user/AGENTS.md | 3 +-- docs/user/getting-started/install.md | 4 ++-- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 23ca7a099..33a46b454 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,7 +41,7 @@ People trust DesignCraft with their layouts; a crash loses their work. **This ou `ROADMAP.md` (committed) is the one-page summary: stage, headline numbers, dimensions, languages, progress log. It follows craftrules' [`standards/progress-docs.md`](https://github.com/storytold/craftrules/blob/main/standards/progress-docs.md). Details: `docs/target-app-parity.md` (assessment), `docs/gaps.md` (ranked work list: pick from the top), `docs/roadmap.md` (milestones, current focus), `docs/parity-checklist.md` (presence checklist, `cargo xtask parity`), and the typography, file-format, UI, hardware and localization parity docs in `docs/`. When work lands, update the affected docs and their status lines, delete or shrink the closed gap, and add a progress-log line to ROADMAP.md. ## User docs -User docs live in `docs/user/` and are published at https://getartcraft.com/docs/designcraft. If a change alters something a user sees or does (menu or dialog labels, install, file formats, errors), update the matching page in `docs/user/` in the same PR, or add one. Rules: `docs/user/AGENTS.md`. +User docs live in `docs/user/` and are published at https://getartcraft.com/docs/designcraft. If a change alters something a user sees or does (menu or dialog labels, install, file formats, errors), update the matching page in `docs/user/` in the same PR, or add one. Rules: `docs/user/AGENTS.md`. Pages describe the latest release. For a change that is not released yet, write that it was added after and is not in a release yet, or update the page when the release ships. ## Contributor credits (About window) diff --git a/docs/user/AGENTS.md b/docs/user/AGENTS.md index 2edbd117c..f24b1cf6a 100644 --- a/docs/user/AGENTS.md +++ b/docs/user/AGENTS.md @@ -36,8 +36,7 @@ either. Write for an artist, not a developer. Only `key: value` and `key: [a, b]` lines work. Quote values that start with a quote or contain ` #`. -Set `verified` to the workspace `version` in the root `Cargo.toml` whenever you check a -page against the current code. +Set `verified` to the latest release (the newest release tag) after checking the page against that tag with `git show :`. Pages describe the latest release users download, not unreleased code on main. ## Folders diff --git a/docs/user/getting-started/install.md b/docs/user/getting-started/install.md index 1344fee7f..b5bcfca54 100644 --- a/docs/user/getting-started/install.md +++ b/docs/user/getting-started/install.md @@ -27,8 +27,8 @@ The app is signed and notarized. Pick one file from the release. Replace `x86_64` with `aarch64` on ARM. -| File | Notes | -|-------------------------------------------|----------------------------------------------------------| +| File | Notes | +|-----------------------------------------------|----------------------------------------------------------| | `designcraft--linux-x86_64.AppImage` | Runs anywhere. | | `designcraft--linux-x86_64.flatpak` | Sandboxed. Install with `flatpak install --user `. | | `designcraft--linux-x86_64.deb` | Debian and Ubuntu. | From 719cfd12c52483c8f6dc5f1bb7308b1508483897 Mon Sep 17 00:00:00 2001 From: Fabio Lussi <198260595+itrycodinganditsbad@users.noreply.github.com> Date: Mon, 12 Oct 2026 05:09:11 +0200 Subject: [PATCH 4/8] docs(user): use the standard section title Co-Authored-By: Claude Opus 5.5 --- docs/user/getting-started/index.md | 2 +- docs/user/getting-started/install.md | 2 +- docs/user/index.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user/getting-started/index.md b/docs/user/getting-started/index.md index 1cde0866a..b9b3c1673 100644 --- a/docs/user/getting-started/index.md +++ b/docs/user/getting-started/index.md @@ -1,5 +1,5 @@ --- -title: Get started +title: Getting started description: Install DesignCraft, then open the sample magazine or start a new document. order: 10 verified: 0.6.0 diff --git a/docs/user/getting-started/install.md b/docs/user/getting-started/install.md index b5bcfca54..1012de44d 100644 --- a/docs/user/getting-started/install.md +++ b/docs/user/getting-started/install.md @@ -43,4 +43,4 @@ ArtCraft Launcher lists DesignCraft and can install and update it for you. See [ ## First run -Open DesignCraft. You land on the start screen. Continue with [Get started](index.md). If the window closes right away, see [DesignCraft closes right after it starts](../troubleshooting/app-closes-at-start.md). +Open DesignCraft. You land on the start screen. Continue with [Getting started](index.md). If the window closes right away, see [DesignCraft closes right after it starts](../troubleshooting/app-closes-at-start.md). diff --git a/docs/user/index.md b/docs/user/index.md index 490155458..d670cdaa7 100644 --- a/docs/user/index.md +++ b/docs/user/index.md @@ -10,7 +10,7 @@ It has spreads and parent pages, text frames that thread from one to the next, p ## Start here -- [Get started](getting-started/index.md) +- [Getting started](getting-started/index.md) - [Install DesignCraft](getting-started/install.md) - [Guides](guides/index.md) - [Troubleshooting](troubleshooting/index.md) From 0638d6f9443e0c61293268ca3f67baa9ebdd4bdf Mon Sep 17 00:00:00 2001 From: Fabio Lussi <198260595+itrycodinganditsbad@users.noreply.github.com> Date: Mon, 12 Oct 2026 07:13:50 +0200 Subject: [PATCH 5/8] docs: pin the docs checker to a commit and its SHA-256 Co-Authored-By: Claude Opus 5.5 --- .github/workflows/docs-check.yml | 19 ++++++++++--------- docs/user/AGENTS.md | 5 +++-- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml index b89a00a88..079b9d414 100644 --- a/.github/workflows/docs-check.yml +++ b/.github/workflows/docs-check.yml @@ -10,6 +10,12 @@ on: permissions: contents: read +env: + # Shared docs checker from storytold/artcraft-services, pinned to one commit + # and its SHA-256. To update it, change both values in a reviewed PR. + CHECKER_COMMIT: 4db0e30fe2c57a1c4c49e390e3711f90910b8d23 + CHECKER_SHA256: bd6b610a708b85fd0aa0491c459bd2800b716e0b8050516fea79e084cfb2a624 + jobs: check: runs-on: ubuntu-latest @@ -18,15 +24,10 @@ jobs: - uses: actions/setup-node@v4 with: node-version: 22 - - name: Download the shared docs checker - id: fetch + - name: Download the pinned docs checker run: | - url=https://raw.githubusercontent.com/storytold/artcraft-services/main/frontend/apps/artcraft-website-next/scripts/docs/core.mjs - if curl -fsSL "$url" -o "$RUNNER_TEMP/docs-core.mjs"; then - echo "ok=1" >> "$GITHUB_OUTPUT" - else - echo "::warning::The docs checker is not published yet; skipping." - fi + url="https://raw.githubusercontent.com/storytold/artcraft-services/$CHECKER_COMMIT/frontend/apps/artcraft-website-next/scripts/docs/core.mjs" + curl -fsSL "$url" -o "$RUNNER_TEMP/docs-core.mjs" + echo "$CHECKER_SHA256 $RUNNER_TEMP/docs-core.mjs" | sha256sum -c - - name: Check docs/user - if: steps.fetch.outputs.ok == '1' run: node "$RUNNER_TEMP/docs-core.mjs" docs/user diff --git a/docs/user/AGENTS.md b/docs/user/AGENTS.md index f24b1cf6a..27975ca2f 100644 --- a/docs/user/AGENTS.md +++ b/docs/user/AGENTS.md @@ -51,10 +51,11 @@ drafts and are not published. ## Check before you push - curl -fsSL https://raw.githubusercontent.com/storytold/artcraft-services/main/frontend/apps/artcraft-website-next/scripts/docs/core.mjs -o /tmp/docs-core.mjs + commit=$(awk '/CHECKER_COMMIT:/ {print $2}' .github/workflows/docs-check.yml) + curl -fsSL "https://raw.githubusercontent.com/storytold/artcraft-services/$commit/frontend/apps/artcraft-website-next/scripts/docs/core.mjs" -o /tmp/docs-core.mjs node /tmp/docs-core.mjs docs/user -CI runs the same check on every PR that touches `docs/user/`. +This uses the same pinned checker as CI (`.github/workflows/docs-check.yml`). ## Support PRs From fb90a508b1ccb64ba8cea2e575e015659417aa85 Mon Sep 17 00:00:00 2001 From: Fabio Lussi <198260595+itrycodinganditsbad@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:09:21 +0200 Subject: [PATCH 6/8] docs: drop the docs workflows until the checker is on artcraft-services main Co-Authored-By: Claude Opus 5.5 --- .github/workflows/docs-check.yml | 33 ------------------------------ .github/workflows/docs-publish.yml | 22 -------------------- docs/user/AGENTS.md | 6 ++---- 3 files changed, 2 insertions(+), 59 deletions(-) delete mode 100644 .github/workflows/docs-check.yml delete mode 100644 .github/workflows/docs-publish.yml diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml deleted file mode 100644 index 079b9d414..000000000 --- a/.github/workflows/docs-check.yml +++ /dev/null @@ -1,33 +0,0 @@ -name: docs-check - -on: - pull_request: - paths: ["docs/user/**"] - push: - branches: [main] - paths: ["docs/user/**"] - -permissions: - contents: read - -env: - # Shared docs checker from storytold/artcraft-services, pinned to one commit - # and its SHA-256. To update it, change both values in a reviewed PR. - CHECKER_COMMIT: 4db0e30fe2c57a1c4c49e390e3711f90910b8d23 - CHECKER_SHA256: bd6b610a708b85fd0aa0491c459bd2800b716e0b8050516fea79e084cfb2a624 - -jobs: - check: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 - with: - node-version: 22 - - name: Download the pinned docs checker - run: | - url="https://raw.githubusercontent.com/storytold/artcraft-services/$CHECKER_COMMIT/frontend/apps/artcraft-website-next/scripts/docs/core.mjs" - curl -fsSL "$url" -o "$RUNNER_TEMP/docs-core.mjs" - echo "$CHECKER_SHA256 $RUNNER_TEMP/docs-core.mjs" | sha256sum -c - - - name: Check docs/user - run: node "$RUNNER_TEMP/docs-core.mjs" docs/user diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml deleted file mode 100644 index df4a412cc..000000000 --- a/.github/workflows/docs-publish.yml +++ /dev/null @@ -1,22 +0,0 @@ -name: docs-publish - -on: - push: - branches: [main] - paths: ["docs/user/**"] - -permissions: {} - -jobs: - rebuild: - runs-on: ubuntu-latest - steps: - - name: Rebuild getartcraft.com - env: - HOOK: ${{ secrets.DOCS_BUILD_HOOK }} - run: | - if [ -z "$HOOK" ]; then - echo "DOCS_BUILD_HOOK is not set; the nightly website build will pick this up." - exit 0 - fi - curl -fsS -X POST -d '{}' "$HOOK?trigger_title=docs%20update%20from%20$GITHUB_REPOSITORY" diff --git a/docs/user/AGENTS.md b/docs/user/AGENTS.md index 27975ca2f..85c2a44be 100644 --- a/docs/user/AGENTS.md +++ b/docs/user/AGENTS.md @@ -51,11 +51,9 @@ drafts and are not published. ## Check before you push - commit=$(awk '/CHECKER_COMMIT:/ {print $2}' .github/workflows/docs-check.yml) - curl -fsSL "https://raw.githubusercontent.com/storytold/artcraft-services/$commit/frontend/apps/artcraft-website-next/scripts/docs/core.mjs" -o /tmp/docs-core.mjs - node /tmp/docs-core.mjs docs/user + node /frontend/apps/artcraft-website-next/scripts/docs/core.mjs docs/user -This uses the same pinned checker as CI (`.github/workflows/docs-check.yml`). +The checker lives in storytold/artcraft-services. A CI check will be added once it is on that repo's main branch. ## Support PRs From 3787187199093c0a189ca76ad733b0eb9a2090cb Mon Sep 17 00:00:00 2001 From: Fabio Lussi <198260595+itrycodinganditsbad@users.noreply.github.com> Date: Tue, 13 Oct 2026 14:31:48 +0200 Subject: [PATCH 7/8] docs: re-verify against 0.7.1 - Open a file: missing IDML parts now open with an Import Warnings alert in the release; drop the "not in a release yet" note. - Place: an image placed into a frame leaves Auto-Fit off (0.7.0). - Install, supported systems: add the 32-bit Windows x86 builds and the RISC-V .deb and .rpm; example version 0.7.1. - Set verified: 0.7.1 on every checked page. - docs/user/CLAUDE.md: a regular file pointing to AGENTS.md instead of a symlink. Co-Authored-By: Claude Opus 5.5 --- docs/user/CLAUDE.md | 2 +- docs/user/faq/indesign-files.md | 2 +- docs/user/faq/is-it-free.md | 2 +- docs/user/faq/supported-systems.md | 6 +++--- docs/user/getting-started/index.md | 2 +- docs/user/getting-started/install.md | 10 +++++----- docs/user/guides/create-a-document.md | 2 +- docs/user/guides/export-a-pdf.md | 2 +- docs/user/guides/open-a-file.md | 6 ++++-- docs/user/guides/place-images-and-text.md | 4 ++-- docs/user/index.md | 2 +- docs/user/troubleshooting/app-closes-at-start.md | 2 +- docs/user/troubleshooting/get-help.md | 2 +- 13 files changed, 23 insertions(+), 21 deletions(-) mode change 120000 => 100644 docs/user/CLAUDE.md diff --git a/docs/user/CLAUDE.md b/docs/user/CLAUDE.md deleted file mode 120000 index 47dc3e3d8..000000000 --- a/docs/user/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/docs/user/CLAUDE.md b/docs/user/CLAUDE.md new file mode 100644 index 000000000..e7bcfb70e --- /dev/null +++ b/docs/user/CLAUDE.md @@ -0,0 +1 @@ +Read `AGENTS.md` in this folder: it has the rules for the user docs. diff --git a/docs/user/faq/indesign-files.md b/docs/user/faq/indesign-files.md index cac429f37..c60e5dd2c 100644 --- a/docs/user/faq/indesign-files.md +++ b/docs/user/faq/indesign-files.md @@ -2,7 +2,7 @@ title: Can DesignCraft open InDesign files? description: DesignCraft opens and exports InDesign Markup (.idml) files. The Open dialog does not list InDesign's own .indd format. order: 30 -verified: 0.6.0 +verified: 0.7.1 --- Yes for IDML, the InDesign Markup format. DesignCraft can open `.idml` files and export them with **File**, then **Export IDML…**. diff --git a/docs/user/faq/is-it-free.md b/docs/user/faq/is-it-free.md index bfa404b8d..ecc1b065a 100644 --- a/docs/user/faq/is-it-free.md +++ b/docs/user/faq/is-it-free.md @@ -2,7 +2,7 @@ title: Is DesignCraft free? description: DesignCraft is free and open source, with no subscription, licence server or telemetry. order: 10 -verified: 0.6.0 +verified: 0.7.1 --- Yes. DesignCraft is free. It has no subscription, no licence server and no telemetry. diff --git a/docs/user/faq/supported-systems.md b/docs/user/faq/supported-systems.md index b6701ac7c..faef29c7c 100644 --- a/docs/user/faq/supported-systems.md +++ b/docs/user/faq/supported-systems.md @@ -2,14 +2,14 @@ title: Which systems does DesignCraft run on? description: DesignCraft runs on Windows 11, macOS and Linux, and in a web browser. order: 20 -verified: 0.6.0 +verified: 0.7.1 --- DesignCraft runs on Windows, macOS and Linux, and in a modern web browser. The release also has builds for FreeBSD. -- **Windows 11**: x64 and arm64 installers, plus portable zips. +- **Windows 11**: x64, arm64 and 32-bit x86 installers, plus portable zips. - **macOS**: one universal build for Apple silicon and Intel. -- **Linux**: x86_64 and aarch64 as AppImage, Flatpak, `.deb`, `.rpm` or tarball, and a RISC-V tarball. +- **Linux**: x86_64 and aarch64 as AppImage, Flatpak, `.deb`, `.rpm` or tarball, and RISC-V as `.deb`, `.rpm` or tarball. - **Web**: a static site you host yourself (`designcraft-web-.zip`). It runs on WebGPU and falls back to WebGL2. The web build has no control channel, and Save and Export download the file. All files are on the [latest release](https://github.com/storytold/designcraft/releases/latest). See [Install DesignCraft](../getting-started/install.md) for steps. diff --git a/docs/user/getting-started/index.md b/docs/user/getting-started/index.md index b9b3c1673..344804ceb 100644 --- a/docs/user/getting-started/index.md +++ b/docs/user/getting-started/index.md @@ -2,7 +2,7 @@ title: Getting started description: Install DesignCraft, then open the sample magazine or start a new document. order: 10 -verified: 0.6.0 +verified: 0.7.1 --- Install DesignCraft first, then start a document. diff --git a/docs/user/getting-started/install.md b/docs/user/getting-started/install.md index 1012de44d..f36c1a0cb 100644 --- a/docs/user/getting-started/install.md +++ b/docs/user/getting-started/install.md @@ -1,11 +1,11 @@ --- title: Install DesignCraft -description: Download DesignCraft 0.6.0 for Windows 11, macOS or Linux, or install it from ArtCraft Launcher. +description: Download DesignCraft 0.7.1 for Windows 11, macOS or Linux, or install it from ArtCraft Launcher. order: 20 -verified: 0.6.0 +verified: 0.7.1 --- -Download the file for your system from the [latest release](https://github.com/storytold/designcraft/releases/latest) and install it. In the file names, `` stands for the version number, for example `0.6.0`. The release also has `SHA256SUMS.txt`, which lists a checksum for every file. The [DesignCraft page on getartcraft.com](https://getartcraft.com/apps/designcraft) links to the download as well. +Download the file for your system from the [latest release](https://github.com/storytold/designcraft/releases/latest) and install it. In the file names, `` stands for the version number, for example `0.7.1`. The release also has `SHA256SUMS.txt`, which lists a checksum for every file. The [DesignCraft page on getartcraft.com](https://getartcraft.com/apps/designcraft) links to the download as well. ## Windows 11 @@ -14,7 +14,7 @@ Download the file for your system from the [latest release](https://github.com/s 3. Run the file and follow the installer. 4. Start **DesignCraft** from the Start menu. -The release also has an `arm64` installer for ARM PCs such as Snapdragon. To run without installing, download `designcraft--windows-x64-portable.zip` (or the `arm64` version), unzip it and start the program inside. The installers and executables are code-signed. +The release also has an `arm64` installer for ARM PCs such as Snapdragon, and a 32-bit `x86` installer. To run without installing, download `designcraft--windows-x64-portable.zip` (or the `arm64` or `x86` version), unzip it and start the program inside. The installers and executables are code-signed. ## macOS @@ -35,7 +35,7 @@ Pick one file from the release. Replace `x86_64` with `aarch64` on ARM. | `designcraft--linux-x86_64.rpm` | Fedora, RHEL and openSUSE. | | `designcraft--linux-x86_64.tar.gz` | Unpack anywhere. | -For RISC-V there is only `designcraft--linux-riscv64.tar.gz`. It needs glibc 2.39 or newer (Ubuntu 24.04 or newer). A FreeBSD build (`designcraft--freebsd-x86_64.tar.gz`) is on the release page too. +For RISC-V there is a `.deb`, an `.rpm` and a tarball, named with `riscv64` in place of `x86_64`. There is no AppImage or Flatpak for RISC-V. The RISC-V build needs glibc 2.39 or newer (Ubuntu 24.04 or newer). A FreeBSD build (`designcraft--freebsd-x86_64.tar.gz`) is on the release page too. ## Install with ArtCraft Launcher diff --git a/docs/user/guides/create-a-document.md b/docs/user/guides/create-a-document.md index 76b95ae56..2ad263dbc 100644 --- a/docs/user/guides/create-a-document.md +++ b/docs/user/guides/create-a-document.md @@ -2,7 +2,7 @@ title: Create a new document description: Start a new DesignCraft document from a preset or with your own page size, margins and columns. order: 10 -verified: 0.6.0 +verified: 0.7.1 --- Choose **File**, then **New Document…** (Ctrl+N), set the page size and margins, and click **OK**. diff --git a/docs/user/guides/export-a-pdf.md b/docs/user/guides/export-a-pdf.md index 938c5dfe2..3bec469cd 100644 --- a/docs/user/guides/export-a-pdf.md +++ b/docs/user/guides/export-a-pdf.md @@ -2,7 +2,7 @@ title: Export a PDF description: Export your DesignCraft document as a PDF for desktop printing, a print shop, screen or archive. order: 40 -verified: 0.6.0 +verified: 0.7.1 --- Choose **File**, then **Export PDF…**, pick a **Preset**, click **OK** and name the file. diff --git a/docs/user/guides/open-a-file.md b/docs/user/guides/open-a-file.md index 2c1568346..f659e5dc7 100644 --- a/docs/user/guides/open-a-file.md +++ b/docs/user/guides/open-a-file.md @@ -2,7 +2,7 @@ title: Open a DesignCraft or InDesign (IDML) file description: Open a .designcraft document or an InDesign Markup (.idml) file, and what to do about missing fonts and incomplete IDML packages. order: 20 -verified: 0.6.0 +verified: 0.7.1 --- Choose **File**, then **Open…** (Ctrl+O), and pick a `.designcraft` or `.idml` file. The file opens as a new document. @@ -27,7 +27,9 @@ Text that uses a font DesignCraft cannot find is highlighted in pink. This is th ## Import warnings -If an IDML package is missing some of its parts, 0.6.0 may not open it. Opening such files with an **Import Warnings** alert that names the missing parts was added after 0.6.0 and is not in a release yet. +If an IDML package is missing some of its parts, DesignCraft still opens it and shows an **Import Warnings** alert that names each missing part. The contents of those parts are not in the document, so check your layout. + +If the package has none of its spreads, there is nothing to open. DesignCraft then shows a **Can't Open the File** alert that names the missing parts. ## Save it again diff --git a/docs/user/guides/place-images-and-text.md b/docs/user/guides/place-images-and-text.md index 3ac9b2382..b89306648 100644 --- a/docs/user/guides/place-images-and-text.md +++ b/docs/user/guides/place-images-and-text.md @@ -2,7 +2,7 @@ title: Place images, PDFs and text description: Bring images, PDF pages, Word and plain text files into a DesignCraft document with File, Place. order: 30 -verified: 0.6.0 +verified: 0.7.1 --- Choose **File**, then **Place…** (Ctrl+D), pick a file, and DesignCraft puts it into your document. @@ -13,7 +13,7 @@ Shortcuts on this page use Ctrl. On macOS, use Cmd instead of Ctrl. 1. Open the **File** menu and choose **Place…**. 2. Pick a file. The dialog's **Graphics and text** filter covers the file types below. -3. For an image, DesignCraft places it in the selected empty frame if there is one. +3. For an image, DesignCraft places it in the selected empty frame if there is one. The image fills the frame once and keeps its proportions. **Auto-Fit** stays off, so resizing the frame later crops the image instead of scaling it. 4. For a text file, it goes into the insertion point, the selected frame, or a new frame. ## File types diff --git a/docs/user/index.md b/docs/user/index.md index d670cdaa7..2b05e5e08 100644 --- a/docs/user/index.md +++ b/docs/user/index.md @@ -1,7 +1,7 @@ --- title: DesignCraft description: DesignCraft is a free, open-source page layout app for print and screen, an alternative to Adobe InDesign. -verified: 0.6.0 +verified: 0.7.1 --- DesignCraft is a page layout and publishing app. It is an open-source alternative to Adobe InDesign, built from scratch by the ArtCraft team. If you know InDesign's tools, menus and panels, you will find them here. diff --git a/docs/user/troubleshooting/app-closes-at-start.md b/docs/user/troubleshooting/app-closes-at-start.md index b8908fe6c..9fb60b1f3 100644 --- a/docs/user/troubleshooting/app-closes-at-start.md +++ b/docs/user/troubleshooting/app-closes-at-start.md @@ -2,7 +2,7 @@ title: DesignCraft closes right after it starts description: On Windows, DesignCraft shows a brief spinner and then closes with no message. Update, or force the DirectX 12 graphics backend. order: 10 -verified: 0.6.0 +verified: 0.7.1 --- If DesignCraft flashes a spinner and closes, update to the [latest release](https://github.com/storytold/designcraft/releases/latest). If it still closes, set the environment variable `WGPU_BACKEND` to `dx12` and start it again. diff --git a/docs/user/troubleshooting/get-help.md b/docs/user/troubleshooting/get-help.md index f8f32fe67..25ab9cd13 100644 --- a/docs/user/troubleshooting/get-help.md +++ b/docs/user/troubleshooting/get-help.md @@ -2,7 +2,7 @@ title: Report a problem description: What to include and where to post when DesignCraft misbehaves or crashes. order: 20 -verified: 0.6.0 +verified: 0.7.1 --- Post in the [issue tracker](https://github.com/storytold/designcraft/issues) or in [Discord](https://discord.gg/artcraft), and attach the log file. The log is the most useful thing you can send after a crash. From a134dbb056367f8c015b3f12f98849b3c80b8ce4 Mon Sep 17 00:00:00 2001 From: Fabio Lussi <198260595+itrycodinganditsbad@users.noreply.github.com> Date: Tue, 13 Oct 2026 22:37:33 +0200 Subject: [PATCH 8/8] Drop the root AGENTS.md docs rule; keep the PR to docs/user/ Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 33a46b454..65693656c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,9 +40,6 @@ People trust DesignCraft with their layouts; a crash loses their work. **This ou ## Roadmap `ROADMAP.md` (committed) is the one-page summary: stage, headline numbers, dimensions, languages, progress log. It follows craftrules' [`standards/progress-docs.md`](https://github.com/storytold/craftrules/blob/main/standards/progress-docs.md). Details: `docs/target-app-parity.md` (assessment), `docs/gaps.md` (ranked work list: pick from the top), `docs/roadmap.md` (milestones, current focus), `docs/parity-checklist.md` (presence checklist, `cargo xtask parity`), and the typography, file-format, UI, hardware and localization parity docs in `docs/`. When work lands, update the affected docs and their status lines, delete or shrink the closed gap, and add a progress-log line to ROADMAP.md. -## User docs -User docs live in `docs/user/` and are published at https://getartcraft.com/docs/designcraft. If a change alters something a user sees or does (menu or dialog labels, install, file formats, errors), update the matching page in `docs/user/` in the same PR, or add one. Rules: `docs/user/AGENTS.md`. Pages describe the latest release. For a change that is not released yet, write that it was added after and is not in a release yet, or update the page when the release ships. - ## Contributor credits (About window) - About ▸ Contributors/Models are compiled into the binary from `contributors/contributors.json`