diff --git a/README.md b/README.md index 020b9c43d..14c086876 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,182 @@ -## Link Checking + +
+ + SignalWire + +

SignalWire Docs

+

Developer documentation for the SignalWire communications platform.
Voice, video, messaging, and AI -- all programmable through a single API.

+

Built with Fern

+
+ + +

+ Live Docs + Discord + CC BY-NC-SA 4.0 + GitHub Stars +

+ + +

+ Get Started  ·  + API Reference  ·  + SWML  ·  + Agents SDK  ·  + Report an Issue +

+ +
+
+ + + SignalWire Docs Homepage + + +
-This repository includes automated link checking to detect broken external links in the documentation. +--- + +## Overview + +This is the source repository for [signalwire.com/docs](https://signalwire.com/docs) -- the developer documentation for the SignalWire platform. The site is built with [Fern](https://buildwithfern.com/) and auto-deployed on every merge to `main`. + +### Products + + + + + + + +
+ +**Products** + +| | Product | Description | +|---|---|---| +| | [Platform](https://signalwire.com/docs/platform) | Dashboard, configuration & administration | +| | [Call Flow Builder](https://signalwire.com/docs/call-flow-builder) | Drag-and-drop call flows and AI agents | -### How It Works + -The link checker uses [Lychee](https://lychee.cli.rs/) to scan all URLs in the documentation sitemap. It handles GitHub URLs specially to avoid rate limiting issues: +**SDKs** -- **GitHub blob/tree/tag URLs** are verified locally by cloning repositories (GitHub blocks automated HTTP requests to these URLs) -- **GitHub issues/PRs/discussions** are checked via HTTP with low concurrency -- **All other URLs** are checked via HTTP with standard concurrency +| | Product | Description | +|---|---|---| +| | [Agents SDK](https://signalwire.com/docs/agents-sdk) | Build AI-powered voice agents | +| | [Server SDK](https://signalwire.com/docs/server-sdk) | Control communications in real time | +| | [Browser SDK](https://signalwire.com/docs/browser-sdk) | Voice, video & chat in the browser | -The checker includes retry logic with exponential backoff for rate-limited (429) responses and falls back to local verification for GitHub 5xx errors. + -### Automated Checks +**APIs & Languages** -Link checking runs automatically in two scenarios: +| | Product | Description | +|---|---|---| +| | [REST APIs](https://signalwire.com/docs/apis) | SMS, calls & account management | +| | [SWML](https://signalwire.com/docs/swml) | Markup language for communication apps | +| | [Compatibility API](https://signalwire.com/docs/compatibility-api) | Drop-in migration from TwiML | -1. **On Pull Requests**: The `preview-docs` workflow generates a preview deployment and checks all links, posting results as a PR comment -2. **Daily Production Check**: A scheduled workflow runs weekdays at 10am UTC to check the production site, with Slack notifications on failure +
-### Local Development +### Structure -To run link checking locally: +``` +signalwire-fern-config/ +├── fern/ +│ ├── products/ # Guides, quickstarts, and reference docs by product +│ ├── apis/ # Generated OpenAPI specs (consumed by Fern) +│ ├── assets/ # Images, icons, and static assets +│ ├── snippets/ # Reusable MDX snippets +│ └── docs.yml # Top-level Fern config (nav, theme, layout) +├── specs/ # TypeSpec source files → compile to OpenAPI +├── scripts/ # Build and CI utilities +└── lychee.toml # Link checker configuration +``` -1. Install [Lychee](https://lychee.cli.rs/): - ```bash - # macOS - brew install lychee +### License - # Linux (cargo) - cargo install lychee +Available under the Creative Commons **CC BY-NC-SA 4.0** license. See [LICENSE](LICENSE) for full terms. - # Or download from releases - # https://github.com/lycheeverse/lychee/releases - ``` +--- + +## Contribute -2. Run the link checker: - ```bash - # Check production sitemap - npm run check-links +Whether you're fixing a typo, reporting missing information, or submitting new content -- all contributions are welcome. - # Check a specific sitemap (e.g., preview deployment) - node scripts/check-links.js --sitemap https://preview-xxx.docs.buildwithfern.com/sitemap.xml +1. [Fork the repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo). +2. Follow the [Usage](#usage) instructions to set up local development. +3. Make your changes and [submit a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). - # Skip GitHub verification for faster checks - node scripts/check-links.js --skip-github +> [!IMPORTANT] +> Contributions to the API docs require additional workflows. +> TypeSpec source files live in `specs/` and compile to OpenAPI specs in `fern/apis/`. +> See the [TypeSpec documentation](https://typespec.io/docs) for guidance on editing spec files. - # See all options - node scripts/check-links.js --help - ``` +### REST API documentation -### Configuration +API reference pages are generated from [TypeSpec](https://typespec.io/docs) definitions in [`specs/`](specs/), which compile into [OpenAPI](https://swagger.io/specification/) spec files consumed by Fern. -Link checker configuration is in `lychee.toml`. Key settings include excluded URLs (analytics, sites that block bots, etc.) and timeout/retry parameters. +```bash +yarn build:specs # Compile TypeSpec → OpenAPI +yarn format:specs # Format spec files +``` --- -## Support +## Usage + +**Prerequisites:** [Node.js](https://nodejs.org/en) (v22+) and [Yarn](https://classic.yarnpkg.com/) (v1). + +```bash +# 1. Clone and install +git clone https://github.com/signalwire/docs.git +cd docs +yarn install + +# 2. Start local dev server (live reload) +yarn start:dev + +# 3. Build (compiles specs + generates Fern preview) +yarn build +``` + +> `yarn start` runs `fern check` before launching the dev server -- use this to validate configuration. + +### Link checking + +Automated link checking via [Lychee](https://lychee.cli.rs/) runs on every PR (results posted as a comment) and daily against production (Slack alerts on failure). + +
+Run locally + +```bash +# Install Lychee +brew install lychee # macOS +cargo install lychee # Linux + +# Check production sitemap +yarn check-links + +# Check a preview deployment +node scripts/check-links.js --sitemap https://preview-xxx.docs.buildwithfern.com/sitemap.xml + +# Skip GitHub verification for faster checks +node scripts/check-links.js --skip-github +``` + +Configuration: `lychee.toml` + +
+ +--- + +## Contact and Support + +The SignalWire Docs are maintained by the **Developer Experience** team. -Need help? [Set up a call](https://buildwithfern.com/contact) with an expert or email us at [support@buildwithfern.com](mailto:support@buildwithfern.com). +| | | +|---|---| +| Questions & feedback | devex@signalwire.com | +| Support portal | [support.signalwire.com](https://support.signalwire.com/hc/en-us) | +| Community | [Discord](https://discord.com/invite/F2WNYTNjuF) | diff --git a/fern/assets/images/img/homepage.png b/fern/assets/images/img/homepage.png new file mode 100644 index 000000000..91f521173 Binary files /dev/null and b/fern/assets/images/img/homepage.png differ