diff --git a/.github/ISSUE_TEMPLATE/writing-feedback.yml b/.github/ISSUE_TEMPLATE/writing-feedback.yml new file mode 100644 index 0000000..205a6e8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/writing-feedback.yml @@ -0,0 +1,46 @@ +name: Writing feedback +description: Tell us how your first session went, or what makes you keep using writui. +title: "Writing feedback: " +body: + - type: markdown + attributes: + value: | + Thanks for trying writui. A few sentences are enough, including if you couldn't get started. + This report is public. Please don't include private writing, passwords, or your vault file. + - type: textarea + id: use-case + attributes: + label: What did you want to write? + description: Describe the kind of writing, not its private contents. + placeholder: For example, a blog draft, journal entry, or work notes. + validations: + required: true + - type: textarea + id: experience + attributes: + label: How did it go? + description: What worked well? Where did you get stuck, or what made you stop? + validations: + required: true + - type: dropdown + id: return-use + attributes: + label: Have you come back to write again? + options: + - This was my first attempt + - Yes, on another day + - No, I stopped using it + - I couldn't get it running + validations: + required: true + - type: textarea + id: next-session + attributes: + label: What would help you use writui again? + description: A change, something to keep as it is, or a reason it isn't for you. + - type: input + id: environment + attributes: + label: Your setup (optional) + description: Operating system, terminal, and writui version, if you know them. + placeholder: For example, macOS, Ghostty, writui 0.17.0. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 62d33ea..92281a3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -101,6 +101,12 @@ site/build.sh # or build it into site/public, as Cloudflare does - **The demo video** on the landing page is recorded with [VHS](https://github.com/charmbracelet/vhs) from `site/demo.tape`; the tape's first lines say how to re-record it. +- **The first-session guide's screenshots** come from + `site/first-session.tape`. From the repo root, run + `bash site/record-first-session.sh` with VHS and `cwebp` installed. It + records the debug app with synthetic writing in a new throwaway vault, + then crops and losslessly compresses the six screenshots as WebP. Raw + screenshots and the review GIF stay in `/tmp/writui-first-session-captures`. ## License diff --git a/README.md b/README.md index 1168473..6588f15 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ A writing app for the terminal. No nonsense. Markdown. Local. Encrypted. +[![Writing in writui](site/static/demo.png)](https://writui.com) + - **Private.** All your posts live in one file, encrypted with your password. Without the password nobody can read them. - **Plain markdown.** You write markdown. Each post starts with a `# Title`. @@ -99,6 +101,12 @@ cargo clippy --all-targets -- -D warnings If both finish without errors, writui's tests pass on your computer. +## Try a five-minute writing session + +[Follow the illustrated guide](https://writui.com/blog/try-a-five-minute-writing-session/) +to create your vault, write your first post, and keep a version to come +back to. Then [tell us how it went](https://github.com/aakashns/writui/issues/new?template=writing-feedback.yml). + ## Use Open a terminal and run: diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 4f18098..76c6713 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -624,3 +624,47 @@ Co-Authored-By lines. Commit bodies are wrapped at about 72 columns and GitHub shows every line break in release notes, so each paragraph or list item is joined back into one line. No "@user in #n" or "New contributors": it's one person's project so far. + +## Promotion starts with writing sessions and voluntary feedback + +On 2026-10-13, the creator chose regular users and useful feedback as the +promotion priority. Start with people who already use the terminal and +write in Markdown. The site and README offer a short session in a +temporary vault with sample text, followed by a public GitHub feedback +form. The form asks about the writing task, friction, and whether someone +has returned on another day; it never asks for their actual writing or +vault. Returning use is self-reported. Downloads, clones, and stars do not +measure active writers. + +Promotion preparation and recurring research can proceed alongside app +development. Keep code and site changes reviewable through PRs, and leave +merging to the creator. External community submissions need an approved +destination and message; respect each community's current rules on +promotion and AI assistance. The creator's blog posts remain theirs. + +## The first-session guide is a blog post using the regular vault + +Later on 2026-10-13, the creator moved the guide off the landing page into +a new blog post, "Try a five-minute writing session". Its link belongs +directly below the demo recording. Readers should install and use writui +normally, choose their own password, and follow illustrated steps to write +and return to a post; they should not be asked to set up a temporary vault. +The README links to the same guide. Its screenshots are recorded from the +debug app with synthetic writing and an isolated throwaway vault, following +the existing development-data rules. + +The creator asked for aggressive image compression and for every screenshot +to load upfront. Ship cropped, lossless WebP images with explicit dimensions +and eager loading, so text stays sharp and the page does not shift as +images arrive. Keep the raw screenshots and review GIF out of the site. + +The guide link is the demo recording's centered, clickable caption. +A thin white border separates each terminal screenshot from the blog +background. +The Markdown example has a Copy button with a brief "Copied" confirmation, +using the same clipboard behavior as the install command. +The introduction ends with "Here are the steps we'll follow:" and links to +each step. Screenshot links open in a new tab, without a sentence telling +readers to click them. The copyable example must retain its literal +Markdown symbols and line breaks, rather than rendering headings or lists +inside the code block. diff --git a/docs/PLAN.md b/docs/PLAN.md index 0376bcf..32a7458 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -12,6 +12,13 @@ file is the source of truth for what's next. ## Next up +Alongside development, focus promotion on regular users and useful feedback. +The first experiment is an illustrated "Try a five-minute writing session" +blog post, linked in the site's demo caption and from the README, with a short +GitHub feedback form. It guides people through using their regular vault. +Learn where new writers get stuck and whether they return on another day. +Keep promotion work in separate PRs from the app milestones below. + The site is on Cloudflare Workers: writui.com serves it (and `install.sh`), and www redirects. Still to do by hand: turn off GitHub Pages for the repo (it's still enabled, with the writui.com domain). diff --git a/docs/SPEC.md b/docs/SPEC.md index 84a2aed..2c9d3c6 100644 --- a/docs/SPEC.md +++ b/docs/SPEC.md @@ -759,6 +759,20 @@ in [DECISIONS.md](DECISIONS.md); the build order lives in [PLAN.md](PLAN.md). the browser allows copying; it says "Copied" for a moment). The landing page is kept up to date with each new feature (see AGENTS.md). "Changelog" in the menu links to the GitHub releases page. +- "Try a five-minute writing session" is the demo recording's clickable, + centered caption. It opens a blog post with screenshots, guiding readers + through + installing the app, choosing their own vault password, writing a post, + saving a version, and returning to their writing. The guide uses normal + `writui`, with no temporary-vault setup. Screenshots are compressed WebP + images with explicit dimensions and a thin white border, and load upfront. + The Markdown example has a Copy button that briefly confirms "Copied". + The introduction links to each step, and screenshots open at full size + in a new tab when clicked. + The README links to the same post. + The guide ends with a short public GitHub feedback form asking about the + writing task, friction, and returning use, without collecting private + writing or vault files. - Posts live in the encrypted vault, but the blog lives in the public repo — so blog posts get into `site/content/blog/` via "export as markdown", with front matter (Zola reads YAML front matter), and are edited by diff --git a/site/content/blog/try-a-five-minute-writing-session.md b/site/content/blog/try-a-five-minute-writing-session.md new file mode 100644 index 0000000..9936faf --- /dev/null +++ b/site/content/blog/try-a-five-minute-writing-session.md @@ -0,0 +1,131 @@ ++++ +title = "Try a five-minute writing session" +description = "Create your vault, write your first post, and pick up where you left off. A step-by-step guide to writui." +date = 2026-10-13 ++++ + +Let's write your first post in writui. You'll choose a password, put a few +thoughts on the page, and save a version to come back to. Here are the steps +we'll follow: + +1. [Install and open writui](#1-install-and-open-writui) +2. [Choose your password](#2-choose-your-password) +3. [Start a post](#3-start-a-post) +4. [Write a few thoughts](#4-write-a-few-thoughts) +5. [Keep a version](#5-keep-a-version) +6. [Come back to it](#6-come-back-to-it) + +## 1. Install and open writui + +On macOS or Linux, paste this into your terminal and press Enter: + +```sh +curl -fsSL https://writui.com/install.sh | bash +``` + +Follow any instructions the installer prints, then open the app: + +```sh +writui +``` + +On Windows, follow the [build instructions](https://github.com/aakashns/writui#windows) +first, then run `writui`. + +## 2. Choose your password + +The first time you open writui, it asks you to create your vault. This is +where your posts and their versions are kept, encrypted on your computer. + +Type a password of at least eight characters, press Tab, and type it again +in **Confirm password**. Press Enter to create your vault. You can also +click either password box to move between them. + +The Create your vault screen with Password and Confirm password fields + +Choose a password you can remember or keep in your password manager. +**There is no password recovery:** forgetting it means losing access to +your writing. If you've already set up writui, enter your existing password +to unlock it instead. + +## 3. Start a post + +You'll see your list of posts. Click **New** or press `n` to start writing. + +The empty post list, with New highlighted above Import and the search field + +The first line already starts with `# `. Type a title, such as +**A little room to think**, then press Enter twice to leave a blank line +before the body. + +## 4. Write a few thoughts + +Write about something on your mind. Or try this short example to see how +Markdown looks: + +
+ + +
Today I want to make a little room for **writing**.
+
+## Things worth noticing
+
+- A good conversation
+- An idea for tomorrow
+- A sentence I want to keep
+
+One quiet paragraph is a good start.
+ +
+ +A post titled A little room to think with a bold word, a heading, and a list + +The text is formatted as you type: `**writing**` becomes bold, `##` starts a +heading, and `-` starts a list. The Markdown marks stay visible, so you can +always see and edit what you typed. + +Your post **saves automatically as you write**. You don't need to press a +save button to keep your changes. + +## 5. Keep a version + +Press Ctrl+K to open the menu. It lists the commands and their shortcuts. +You can click a command, move to it with the arrow keys and press Enter, +or type part of its name to find it. + +The command menu showing Save version, History, Export as markdown, and other commands + +Choose **Save version**, or close the menu with Esc and press Ctrl+S. +Name the version **First thoughts**, then press Enter. + +The Save version dialog with First thoughts entered as the version name + +A version keeps a snapshot of your post. It's useful when you want to +try a different direction without losing the earlier one. Open **History** +from the menu, or press Ctrl+R, to see the version you just saved. Press +Esc to return to writing. + +## 6. Come back to it + +Press Esc in the editor to return to your posts. Click your post to open it, +or select it with the arrow keys and press Enter. + +The post list with A little room to think saved and selected + +When you're done for now, press Ctrl+Q to quit. Next time, run `writui`, +enter your password, and you'll be back where you left off. To lock it +without quitting, press Ctrl+O; unlocking brings you back to the same place. + +To keep a Markdown copy outside writui, open the menu and choose +**Export as markdown**. Exported files are ordinary text files, so store +them somewhere suitable for what you've written. + +## How did it go? + +[Tell us about your writing session](https://github.com/aakashns/writui/issues/new?template=writing-feedback.yml). +What did you want to write? Did anything get in your way? Would you come +back to it tomorrow? If you've already been using writui, we'd like to +hear what makes you keep using it too. + +GitHub feedback is public, so describe your experience without including +private writing or your password. diff --git a/site/first-session.tape b/site/first-session.tape new file mode 100644 index 0000000..f2d35a0 --- /dev/null +++ b/site/first-session.tape @@ -0,0 +1,92 @@ +# Screenshots for the first writing session guide. From the repo root: +# bash site/record-first-session.sh +# Raw screenshots and a review GIF go to /tmp/writui-first-session-captures. +# This uses the debug app, synthetic writing, and a new throwaway vault. +# The public guide itself uses the normal installed app and a personal password. + +Output "/tmp/writui-first-session-captures/flow.gif" + +Set Shell "bash" +Set FontSize 22 +Set Width 1200 +Set Height 760 +Set Padding 20 +Set Framerate 10 +Set TypingSpeed 5ms +Set Theme { "name": "writui", "background": "#111113", "foreground": "#e4e4e7", "cursor": "#e4e4e7", "selection": "#3a3a40", "black": "#18181b", "red": "#f87171", "green": "#86d39b", "yellow": "#facc15", "blue": "#7aa2f7", "magenta": "#c084fc", "cyan": "#67d4e8", "white": "#e4e4e7", "brightBlack": "#6b6b73", "brightRed": "#fca5a5", "brightGreen": "#a7e3b6", "brightYellow": "#fde68a", "brightBlue": "#a5c0fb", "brightMagenta": "#d8b4fe", "brightCyan": "#a5e8f3", "brightWhite": "#ffffff" } + +Hide +Type "writui_guide_dir=$(mktemp -d /tmp/writui-guide.XXXXXX)" +Enter +Type 'target/debug/writui --db "$writui_guide_dir/writui.db"' +Enter +Sleep 1.5s +Show +Screenshot "/tmp/writui-first-session-captures/create-vault.png" +Sleep 1s +Type "writui-dev" +Tab +Type "writui-dev" +Enter +Sleep 1s +Screenshot "/tmp/writui-first-session-captures/new-post.png" +Sleep 1s +Type "n" +Sleep 300ms +Type "A little room to think" +Enter +Enter +Type "Today I want to make a little room for **writing**." +Enter +Enter +Type "## Things worth noticing" +Enter +Enter +Type "- A good conversation" +Enter +Type "- An idea for tomorrow" +Enter +Type "- A sentence I want to keep" +Enter +Enter +Type "One quiet paragraph is a good start." +Sleep 800ms +Screenshot "/tmp/writui-first-session-captures/writing.png" +Sleep 1s +Ctrl+K +Sleep 500ms +Screenshot "/tmp/writui-first-session-captures/menu.png" +Sleep 1s +Type "save" +Enter +Sleep 300ms +Type "First thoughts" +Sleep 300ms +Screenshot "/tmp/writui-first-session-captures/save-version.png" +Sleep 1s +Enter +Sleep 500ms +Ctrl+R +Sleep 500ms +Screenshot "/tmp/writui-first-session-captures/history.png" +Sleep 1s +Escape +Sleep 300ms +Escape +Sleep 500ms +Screenshot "/tmp/writui-first-session-captures/posts.png" +Sleep 1s +Enter +Sleep 500ms +Ctrl+O +Sleep 500ms +Screenshot "/tmp/writui-first-session-captures/unlock.png" +Sleep 1s +Type "writui-dev" +Enter +Sleep 1s +Screenshot "/tmp/writui-first-session-captures/reopened.png" +Sleep 1s +Hide +Ctrl+Q +Sleep 500ms diff --git a/site/record-first-session.sh b/site/record-first-session.sh new file mode 100644 index 0000000..6766b3c --- /dev/null +++ b/site/record-first-session.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env bash +# Run from the repo root. Requires VHS and cwebp (from libwebp). +set -euo pipefail + +cargo build +mkdir -p /tmp/writui-first-session-captures site/static/blog/first-session +vhs site/first-session.tape + +# Crop to the relevant controls, keeping screenshot text pixel-perfect. +# In particular, exclude the setup screen's development path and note. +# -z 9 uses the strongest lossless preset; no PNGs or GIF ship on the site. +encode() { + local screen="$1" x="$2" y="$3" width="$4" height="$5" + cwebp -quiet -z 9 -exact -metadata none -crop "$x" "$y" "$width" "$height" \ + "/tmp/writui-first-session-captures/$screen.png" \ + -o "site/static/blog/first-session/$screen.webp" +} + +encode create-vault 100 10 1000 360 +encode new-post 100 10 1000 300 +encode writing 100 10 1000 350 +encode menu 100 10 1000 600 +encode save-version 200 240 800 260 +encode posts 100 10 1000 280 diff --git a/site/static/blog/first-session/create-vault.webp b/site/static/blog/first-session/create-vault.webp new file mode 100644 index 0000000..fab5c2a Binary files /dev/null and b/site/static/blog/first-session/create-vault.webp differ diff --git a/site/static/blog/first-session/menu.webp b/site/static/blog/first-session/menu.webp new file mode 100644 index 0000000..56504c2 Binary files /dev/null and b/site/static/blog/first-session/menu.webp differ diff --git a/site/static/blog/first-session/new-post.webp b/site/static/blog/first-session/new-post.webp new file mode 100644 index 0000000..53708d0 Binary files /dev/null and b/site/static/blog/first-session/new-post.webp differ diff --git a/site/static/blog/first-session/posts.webp b/site/static/blog/first-session/posts.webp new file mode 100644 index 0000000..2aeed88 Binary files /dev/null and b/site/static/blog/first-session/posts.webp differ diff --git a/site/static/blog/first-session/save-version.webp b/site/static/blog/first-session/save-version.webp new file mode 100644 index 0000000..72e3bff Binary files /dev/null and b/site/static/blog/first-session/save-version.webp differ diff --git a/site/static/blog/first-session/writing.webp b/site/static/blog/first-session/writing.webp new file mode 100644 index 0000000..9a1a410 Binary files /dev/null and b/site/static/blog/first-session/writing.webp differ diff --git a/site/static/copy.js b/site/static/copy.js new file mode 100644 index 0000000..26d10c8 --- /dev/null +++ b/site/static/copy.js @@ -0,0 +1,14 @@ +// Keep the text selectable when clipboard access is unavailable. +for (const button of document.querySelectorAll("button.copy")) { + button.hidden = !navigator.clipboard; + button.addEventListener("click", async () => { + const text = document.getElementById(button.dataset.copy).textContent; + try { + await navigator.clipboard.writeText(text); + button.textContent = "Copied"; + } catch { + button.textContent = "Couldn't copy"; + } + setTimeout(() => { button.textContent = "Copy"; }, 1500); + }); +} diff --git a/site/static/style.css b/site/static/style.css index fe7291a..cca6395 100644 --- a/site/static/style.css +++ b/site/static/style.css @@ -144,6 +144,12 @@ footer.site a { color: inherit; } border: 1px solid var(--faint); background: #000; } +.demo figcaption { + margin-top: 0.65rem; + text-align: center; + color: var(--muted); + font-size: 0.9rem; +} @media (max-width: 48rem) { .demo { margin: 2rem 0; } } @@ -167,6 +173,8 @@ footer.site a { color: inherit; } cursor: pointer; } .copy:hover, .copy:focus-visible { color: var(--text); border-color: var(--muted); } +.writing-example pre { padding-top: 2.8em; } +.writing-example .copy { top: 0.6em; transform: none; } .install .note { color: var(--muted); font-size: 0.9em; } /* Blog lists */ @@ -185,3 +193,9 @@ footer.site a { color: inherit; } header.post { margin-bottom: 2rem; } header.post h1 { margin-bottom: 0.3em; } + +.terminal-screenshot { + display: block; + border: 1px solid #fff; + border-radius: 6px; +} diff --git a/site/templates/base.html b/site/templates/base.html index 0dd74f7..4a81fa2 100644 --- a/site/templates/base.html +++ b/site/templates/base.html @@ -36,6 +36,7 @@ {%- endif %} + diff --git a/site/templates/index.html b/site/templates/index.html index 18b4ee9..7d394b7 100644 --- a/site/templates/index.html +++ b/site/templates/index.html @@ -23,26 +23,10 @@

A writing app for the terminal.

Then run writui. Upgrade later with writui upgrade. On Windows, build it from source.

- -
+
Try a five-minute writing session