Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .docs/user-guide-site/brief.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Brief: YourSSH documentation site on Mintlify

What: move the YourSSH user and developer guides (app repo `docs/wiki/`) into this Mintlify site, refreshed for the 0.4.0 redesign with screenshots from the isolated docs journey, and build/deploy it from GitHub Actions.

Why: the owner wants a public documentation site for YourSSH maintained in YoursshLabs/docs.
4 changes: 4 additions & 0 deletions .docs/user-guide-site/changelog.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Changelog

- 2026-11-13: Starter replaced (branding, navigation, screenshots), CI workflow added, writers dispatched.
- 2026-11-13: 25 pages written by 6 writers, fact-checked against develop by 2 reviewers (app copy bugs fixed in YourSSH PRs #126, #128; plugin globals made real in #127; app lock over every route in progress). validate + broken-links pass. 125 screenshots kept (unused ones pruned).
6 changes: 6 additions & 0 deletions .docs/user-guide-site/context.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# Context

- The repo was created from Mintlify's hosted starter ("Initial commit from Mintlify hosted docs"), so a Mintlify project is connected to it.
- Static export (`mint export`) is Enterprise-only, so self-hosting on GitHub Pages is not an option. CI therefore validates the build and triggers the hosted deployment through the Mintlify API (`POST /v1/project/update/{projectId}`, then poll `GET /v1/project/update-status/{statusId}`: queued | in_progress | success | failure | skipped).
- Screenshots: 209 PNGs from the app repo's `tool/docs_journey.sh` run at v0.4.0 (demo containers, isolated HOME); the mobile pair QR was re-encoded to 192.0.2.10.
- Old content: app repo `docs/wiki/User-Guide-*.md`, `Developer-Guide-*.md`, `docs/SYNC_SETUP.md`, `docs/plugin-authoring-guide.md`.
6 changes: 6 additions & 0 deletions .docs/user-guide-site/plan.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# Plan

1. Replace the starter: branding (amber palette, logo, favicon), navigation for 25 pages (User guide + Developer guide tabs), screenshots under images/.
2. CI: `.github/workflows/docs.yml` — validate + broken links on PRs and main; deploy job on main via the Mintlify API (secrets MINTLIFY_API_KEY, MINTLIFY_PROJECT_ID; skipped when absent).
3. Write the pages (4 writers in parallel, one per section group), then the developer guide after the plugin API fix lands in the app repo.
4. Validate locally, prune unreferenced images, open the PR, merge after CI, ask the owner for the two secrets.
69 changes: 69 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
name: Docs

on:
pull_request:
push:
branches: [main]
workflow_dispatch:

permissions:
contents: read

concurrency:
group: docs-${{ github.ref }}
cancel-in-progress: true

jobs:
build:
name: Build and check
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- name: Install the Mintlify CLI
run: npm i -g mint
- name: Validate the build
run: mint validate
- name: Check links
run: mint broken-links

deploy:
name: Deploy to Mintlify
needs: build
if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
env:
MINTLIFY_API_KEY: ${{ secrets.MINTLIFY_API_KEY }}
MINTLIFY_PROJECT_ID: ${{ secrets.MINTLIFY_PROJECT_ID }}
steps:
- name: Trigger the deployment and wait for it
run: |
set -euo pipefail
if [ -z "${MINTLIFY_API_KEY}" ] || [ -z "${MINTLIFY_PROJECT_ID}" ]; then
echo "::warning::MINTLIFY_API_KEY / MINTLIFY_PROJECT_ID are not set; skipping the API deployment."
exit 0
fi
api=https://api.mintlify.com/v1
resp=$(curl -fsS -X POST "$api/project/update/${MINTLIFY_PROJECT_ID}" \
-H "Authorization: Bearer ${MINTLIFY_API_KEY}")
status_id=$(echo "$resp" | jq -r '.statusId // empty')
if [ -z "$status_id" ]; then
echo "::error::Mintlify did not return a statusId: $resp"
exit 1
fi
echo "Deployment queued: $status_id"
for i in $(seq 1 60); do
sleep 10
st=$(curl -fsS "$api/project/update-status/${status_id}" \
-H "Authorization: Bearer ${MINTLIFY_API_KEY}" | jq -r '.status // empty')
echo "status: ${st:-unknown}"
case "$st" in
success) echo "Deployed."; exit 0 ;;
skipped) echo "::notice::Mintlify skipped the update (nothing to deploy)."; exit 0 ;;
failure) echo "::error::Mintlify deployment failed"; exit 1 ;;
esac
done
echo "::error::Timed out waiting for the Mintlify deployment"
exit 1
3 changes: 3 additions & 0 deletions .mintignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,6 @@
# Draft content
drafts/
*.draft.mdx

# Task notes for maintainers (not published)
.docs/
53 changes: 29 additions & 24 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,33 +1,38 @@
> **First-time setup**: Customize this file for your project. Prompt the user to customize this file for their project.
> For Mintlify product knowledge (components, configuration, writing standards),
> install the Mintlify skill: `npx skills add https://mintlify.com/docs`

# Documentation project instructions
# YourSSH documentation — instructions for writers and agents

## About this project

- This is a documentation site built on [Mintlify](https://mintlify.com)
- Pages are MDX files with YAML frontmatter
- Configuration lives in `docs.json`
- Run `mint dev` to preview locally
- Run `mint broken-links` to check links
- The documentation site for [YourSSH](https://github.com/YoursshLabs/yourssh), built on [Mintlify](https://mintlify.com).
- Pages are MDX files with YAML frontmatter (`title`, `description`, optional `icon` from Lucide/Font Awesome).
- Configuration and navigation live in `docs.json`. A page that is not listed there is not published.
- Preview: `npx mint dev`. Before a pull request: `npx mint validate` and `npx mint broken-links` (CI runs both).
- Screenshots live in `images/<NN-section>/<NN-step>.png`. They come from the app repo's isolated docs journey (`tool/docs_journey.sh` in YoursshLabs/yourssh) and are resized to at most 1440 px wide. Reuse those names; don't add screenshots of real servers, real IPs or real user data.

## Terminology

{/* Add product-specific terms and preferred usage */}
{/* Example: Use "workspace" not "project", "member" not "user" */}

## Style preferences

{/* Add any project-specific style rules below */}

- Use active voice and second person ("you")
- Keep sentences concise — one idea per sentence
- Use sentence case for headings
- Bold for UI elements: Click **Settings**
- Code formatting for file names, commands, paths, and code references
- **YourSSH** (one word, capital Y, S, S, H). "The app" is fine after the first mention.
- **Host**: a saved connection profile (SSH, RDP or VNC). Not "server" when you mean the saved profile.
- **Session** / **tab**: a connected terminal, RDP or VNC view in the top tab bar.
- **Hosts dashboard**: the Home screen with group cards and host cards.
- **Host editor**: the side panel that opens from **New host** or **Edit**.
- **Connection chain**: jump hosts (bastions) in front of a host. Not "proxy jump" in headings.
- **Keychain**: the SSH key manager screen. The macOS Keychain / Windows Credential Manager is the **system credential store**.
- **Known hosts**: pinned host keys. **Host key**: the server's SSH key. Don't call it a fingerprint unless you mean the SHA-256 string.
- **Plugins**: built-in plugins (Snippets, DevOps Hub, Web Tools) and script plugins (JavaScript in `~/.yourssh/plugins`).

## Style

- Active voice, second person ("you"), present tense. One idea per sentence.
- Sentence case for headings and titles.
- Bold for UI labels exactly as the app shows them: click **New host**, then **Save**.
- Code formatting for file names, paths, commands, keys and settings values: `~/.ssh/config`, `Ctrl+Shift+I`.
- Keyboard shortcuts: show macOS first, then Windows/Linux when they differ (`Cmd+K` / `Ctrl+K`).
- Use Mintlify components where they help: `<Steps>` for procedures, `<Note>`/`<Tip>`/`<Warning>` sparingly, `<Frame>` around screenshots with a short caption, `<CardGroup>` on overview pages, `<Tabs>` for per-OS instructions.
- Every screenshot has meaningful alt text.
- Document what the app does today. If you're unsure whether a feature exists or how it behaves, check the app repo (`CLAUDE.md`, `app/lib`) instead of guessing.

## Content boundaries

{/* Define what should and shouldn't be documented */}
{/* Example: Don't document internal admin features */}
- User guide: what a user sees and does, plus the security behaviour they need to understand (host key pinning, credential storage, what syncs and how it's encrypted).
- Developer guide: building from source, architecture, plugin system and plugin authoring.
- Don't document internal process docs (`docs/superpowers/` in the app repo), unreleased features or roadmap items as if they shipped.
8 changes: 3 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
> **Customize this file**: Tailor this template to your project by noting specific contribution types you're looking for, adding a Code of Conduct, or adjusting the writing guidelines to match your style.

# Contribute to the documentation

Thank you for your interest in contributing to our documentation! This guide will help you get started.
Expand All @@ -15,14 +13,14 @@ Thank you for your interest in contributing to our documentation! This guide wil
### Option 2: Local development

1. Fork and clone this repository
2. Install the Mintlify CLI: `npm i -g mint`
2. Install Node.js 20.17+ (the CLI runs with `npx mint`)
3. Create a branch for your changes
4. Make changes
5. Navigate to the docs directory and run `mint dev`
5. Run `npx mint dev`
6. Preview your changes at `http://localhost:3000`
7. Commit your changes and submit a pull request

For more details on local development, see our [development guide](development.mdx).
Run `npx mint validate` and `npx mint broken-links` before opening a pull request; CI runs both. Follow [AGENTS.md](AGENTS.md) for style and terminology.

## Writing guidelines

Expand Down
61 changes: 19 additions & 42 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,55 +1,32 @@
# Mintlify Starter Kit
# YourSSH documentation

Use the starter kit to get your docs deployed and ready to customize.
Source of the YourSSH documentation site, built with [Mintlify](https://mintlify.com). The app lives in [YoursshLabs/yourssh](https://github.com/YoursshLabs/yourssh).

Click the green **Use this template** button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with

- Guide pages
- Navigation
- Customizations
- API reference pages
- Use of popular components

**[Follow the full quickstart guide](https://starter.mintlify.com/quickstart)**

## AI-assisted writing

Set up your AI coding tool to work with Mintlify:
## Preview locally

```bash
npx skills add https://mintlify.com/docs
```

This command installs Mintlify's documentation skill for your configured AI tools like Claude Code, Cursor, Windsurf, and others. The skill includes component reference, writing standards, and workflow guidance.

See the [AI tools guides](/ai-tools) for tool-specific setup.

## Development

Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command:

```
npm i -g mint
npx mint dev # http://localhost:3000
npx mint validate # the same build check CI runs
npx mint broken-links
```

Run the following command at the root of your documentation, where your `docs.json` is located:

```
mint dev
```
Requires Node.js 20.17 or newer.

View your local preview at `http://localhost:3000`.
## Structure

## Publishing changes
- `docs.json` — site config and navigation. A page must be listed here to be published.
- `index.mdx`, `installation.mdx`, `quickstart.mdx` — getting started.
- `user-guide/` — one page per feature.
- `developer-guide/` — building from source, architecture and plugins.
- `images/<NN-section>/` — screenshots from the app repo's isolated docs journey (`tool/docs_journey.sh`), resized to at most 1440 px wide.

Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app) to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch.
Writing rules and terminology: [AGENTS.md](AGENTS.md).

## Need help?
## Build and deploy

### Troubleshooting
`.github/workflows/docs.yml`:

- If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI.
- If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`.
- Every pull request and every push to `main` run `mint validate` and `mint broken-links`.
- After those pass on `main`, the workflow asks Mintlify to deploy the site and waits for the result. It uses the repository secrets `MINTLIFY_API_KEY` (an admin API key, `mint_…`) and `MINTLIFY_PROJECT_ID`, both from the Mintlify dashboard's API keys page. Without them the deploy step is skipped with a warning.

### Resources
- [Mintlify documentation](https://mintlify.com/docs)
To make CI the only way the site deploys, turn off automatic deployments for this repository in the Mintlify dashboard after adding the secrets.
43 changes: 0 additions & 43 deletions ai-tools/claude-code.mdx

This file was deleted.

39 changes: 0 additions & 39 deletions ai-tools/cursor.mdx

This file was deleted.

39 changes: 0 additions & 39 deletions ai-tools/windsurf.mdx

This file was deleted.

4 changes: 0 additions & 4 deletions api-reference/endpoint/create.mdx

This file was deleted.

4 changes: 0 additions & 4 deletions api-reference/endpoint/delete.mdx

This file was deleted.

Loading