Repository navigation
Add hidden Fern instructions pages for coding agents #7723
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
michaelpratt-postman
wants to merge
4
commits into
main
Choose a base branch
from
devin/1793636034-fern-instructions-pages
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+1,918
−2
Open
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
e68e68a
Add hidden Fern instructions pages for coding agents
michaelpratt-postman fab47dc
Add AGENTS.md rule to keep fern-instructions pages in sync
michaelpratt-postman f1457d7
Point page-directive at Fern instructions index, guests are docs-only…
michaelpratt-postman fdfcebd
AGENTS.md: add redirects when moving fern-instructions pages
michaelpratt-postman File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
29 changes: 29 additions & 0 deletions
29
fern/products/home/pages/fern-instructions/access-team.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| --- | ||
| title: Manage a Fern organization | ||
| slug: fern-instructions/access/team | ||
| description: Manage Fern Dashboard members and permissions, organization tokens, SSO, custom domains, and the connected GitHub repository. | ||
| --- | ||
|
|
||
| Use this for organization-level access, not for gating docs readers (see `docs access`). | ||
|
|
||
| ## Workflow | ||
|
|
||
| 1. Check the identity in use with `fern whoami`. | ||
| 2. Members and roles are managed in the [Fern Dashboard](https://dashboard.buildwithfern.com). The user does this in the browser. | ||
| 3. Tokens for CI: `fern token` creates one. `fern org token list`, `fern org token create` and `fern org token revoke` manage them. | ||
| 4. Organization settings: `fern org get` shows them, and `fern org set cli-version` / `fern org unset cli-version` control the CLI version policy. | ||
| 5. Dashboard settings cover SSO, API keys, the connected GitHub repo, custom domains, password protection and PDF export. | ||
|
|
||
| ## Rules | ||
|
|
||
| - Only organization admins can change members, tokens and settings. If a command fails with a permission error, the user needs an admin. | ||
| - Revoke tokens that leak or are no longer used. | ||
|
|
||
| ## Reference | ||
|
|
||
| - [Dashboard overview](https://buildwithfern.com/learn/dashboard/getting-started/overview.md) | ||
| - [Permissions](https://buildwithfern.com/learn/dashboard/configuration/permissions.md) | ||
| - [API keys](https://buildwithfern.com/learn/dashboard/configuration/api-keys.md) | ||
| - [SSO](https://buildwithfern.com/learn/dashboard/configuration/sso.md) | ||
| - [GitHub repository](https://buildwithfern.com/learn/dashboard/configuration/github-repo.md) | ||
| - [General CLI commands](https://buildwithfern.com/learn/cli-api-reference/cli-reference/general-commands.md) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| --- | ||
| title: Automate Fern in CI | ||
| slug: fern-instructions/automate | ||
| description: Run fern check on pull requests, publish docs previews per pull request, publish docs on merge, and release SDKs from CI with FERN_TOKEN. | ||
| --- | ||
|
|
||
| Use this to set up or fix a CI workflow that runs the Fern CLI. | ||
|
|
||
| ## Workflow | ||
|
|
||
| 1. Create an organization token with `fern token` and store it as a CI secret named `FERN_TOKEN`. Never print or commit it. | ||
| 2. Pin a concrete CLI `version` in `fern.config.json` so CI and local runs match. Install the CLI in CI with `fern-api/setup-fern-cli@v1` (GitHub Actions) or `npm install -g fern-api`. | ||
| 3. Add the jobs the user needs: | ||
| - Pull requests: `fern check`. | ||
| - Docs preview per pull request: `fern generate --docs --preview --id <branch> --no-prompt`, then post the printed URL (`Published docs to <url>`, on stderr) as a comment. | ||
| - Docs on merge to the default branch: `fern generate --docs --no-prompt`. | ||
| - SDK release: `fern generate --target <language> --version <version> --force` (or `--group` for `generators.yml`). | ||
| 4. Skip secret-dependent jobs on fork and Dependabot pull requests, which don't receive secrets. | ||
| 5. To keep the spec current, add the `fern-api/sync-openapi` action. See `spec sync`. | ||
|
|
||
| ## Rules | ||
|
|
||
| - Pass `--no-prompt` or `--force` to anything that can prompt. Prompts fail immediately when stdin isn't a TTY or `CI` is set. | ||
| - Don't use `fern login` or `--guest` in CI. Use `FERN_TOKEN`. | ||
| - Run the command from the folder that contains `fern/`. | ||
|
|
||
| ## Verify | ||
|
|
||
| - `fern whoami` in a CI step reports an organization token. The workflow passes on a test pull request and posts a working preview link. | ||
|
|
||
| ## Reference | ||
|
|
||
| - [Publish your docs](https://buildwithfern.com/learn/docs/preview-publish/publishing-your-docs.md) | ||
| - [Preview changes](https://buildwithfern.com/learn/docs/preview-publish/preview-changes.md) | ||
| - [Sync your OpenAPI spec](https://buildwithfern.com/learn/api-definitions/openapi/sync-your-open-api-specification.md) | ||
28 changes: 28 additions & 0 deletions
28
fern/products/home/pages/fern-instructions/cli-generator.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| --- | ||
| title: Generate a CLI from an API definition | ||
| slug: fern-instructions/cli-generator | ||
| description: Generate a command-line tool for an API with Fern, configure commands and auth, and publish it. | ||
| --- | ||
|
|
||
| Use this when the user wants a CLI for their API, not to use the Fern CLI itself. | ||
|
|
||
| ## Workflow | ||
|
|
||
| 1. Follow the CLI generator quickstart to add the generator to the project. | ||
| 2. Configure commands, auth and output from the configuration, authentication and customization pages. Add custom commands where the generated ones aren't enough. | ||
| 3. Generate locally to try it, then set up publishing. | ||
|
|
||
| ## Rules | ||
|
|
||
| - Command names come from the spec. Fix them there or with the generator's OpenAPI extensions. | ||
| - Look up configuration keys on the CLI generator pages. Don't reuse SDK keys. | ||
|
|
||
| ## Reference | ||
|
|
||
| - [Overview](https://buildwithfern.com/learn/cli-generator/get-started/overview.md) | ||
| - [Quickstart](https://buildwithfern.com/learn/cli-generator/get-started/quickstart.md) | ||
| - [Configuration](https://buildwithfern.com/learn/cli-generator/get-started/configuration.md) | ||
| - [Authentication](https://buildwithfern.com/learn/cli-generator/get-started/authentication.md) | ||
| - [Custom commands](https://buildwithfern.com/learn/cli-generator/get-started/custom-commands.md) | ||
| - [Local generation](https://buildwithfern.com/learn/cli-generator/get-started/local-generation.md) | ||
| - [Publishing](https://buildwithfern.com/learn/cli-generator/get-started/publishing.md) |
41 changes: 41 additions & 0 deletions
41
fern/products/home/pages/fern-instructions/docs/access.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| --- | ||
| title: Restrict access to Fern docs | ||
| slug: fern-instructions/docs/access | ||
| description: Gate Fern docs with a password, SSO, JWT, or OAuth, show content by role with RBAC, and inject readers' API keys into the API Explorer. | ||
| --- | ||
|
|
||
| Use this to make some or all of a site private. | ||
|
nerminamiller-postman marked this conversation as resolved.
Resolved
|
||
|
|
||
| ## Pick a method | ||
|
|
||
| | Need | Method | | ||
| |---|---| | ||
| | Quick gate with a shared password, no per-user accounts | Password protection (several passwords can map to roles) | | ||
| | Internal docs behind the company's login (Okta, Google Workspace and others) | SSO | | ||
| | Use the product's own login and control the flow yourself | JWT | | ||
| | Use the product's own login, with Fern running the flow through the OAuth provider | OAuth | | ||
|
|
||
| JWT, OAuth and SSO set a `fern_token` cookie that tells Fern who the reader is and which roles they have. Add RBAC to show different pages, sections or content to different roles, and API key injection to pre-fill the reader's key in the API Explorer. | ||
|
|
||
| ## Workflow | ||
|
|
||
| 1. Confirm the method with the user. Most methods need setup by Fern or values only the user has, such as an identity provider, a signing secret or OAuth client credentials. Don't invent them. | ||
| 2. Follow the setup page for that method. | ||
| 3. For RBAC, define roles in `docs.yml` and restrict navigation entries or page content to them, as described on the RBAC page. | ||
| 4. Preview with `fern docs dev`. It includes a role selector and password login for sites that use them. | ||
|
|
||
| ## Rules | ||
|
|
||
| - Never commit secrets such as JWT signing keys to the repo. | ||
| - Hiding a page (`hidden: true`) doesn't protect it. Anyone with the URL can open it. Use one of the methods above for content that must stay private. | ||
|
|
||
| ## Verify | ||
|
|
||
| - Signed out, protected pages redirect to login or ask for the password. Signed in with each role, the reader sees exactly that role's content. | ||
|
|
||
| ## Reference | ||
|
|
||
| - [Authentication overview](https://buildwithfern.com/learn/docs/authentication/overview.md) | ||
| - [Password protection](https://buildwithfern.com/learn/docs/authentication/setup/password-protection.md), [SSO](https://buildwithfern.com/learn/docs/authentication/setup/sso.md), [JWT](https://buildwithfern.com/learn/docs/authentication/setup/jwt.md), [OAuth](https://buildwithfern.com/learn/docs/authentication/setup/oauth.md) | ||
| - [RBAC](https://buildwithfern.com/learn/docs/authentication/features/rbac.md) | ||
| - [API key injection](https://buildwithfern.com/learn/docs/authentication/features/api-key-injection.md) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| --- | ||
| title: Configure AI features in Fern docs | ||
| slug: fern-instructions/docs/ai | ||
| description: Control llms.txt, Markdown access, agent directives, Ask Fern, the docs MCP server, and hosted agent skills on a Fern site. | ||
| --- | ||
|
|
||
| Use this to change what AI agents and the site's AI assistant see. | ||
|
|
||
| ## What every Fern site serves | ||
|
|
||
| - `/llms.txt`: an index of pages, each with a `.md` link. | ||
| - `<page URL>.md`: any page as Markdown. Agents should fetch this rather than HTML. | ||
| - `/_mcp/server`: an MCP server with `searchDocs` and `fetchPage` tools. For example, Fern's own docs: `https://buildwithfern.com/learn/_mcp/server`. | ||
|
|
||
| ## Workflow | ||
|
|
||
| 1. Agent-facing settings go under `agents` in `docs.yml`: | ||
| - `agents.page-directive`: the instruction added to the top of every `.md` page. | ||
| - `agents.page-description-source`: where page descriptions in `llms.txt` come from. | ||
| - `agents.llms-txt` and `agents.robots-txt`: control those files. | ||
| 2. Content for one audience only: wrap it in `<llms-only>` (shown to agents in `.md`, hidden on the site) or `<llms-ignore>` (shown on the site, left out of `.md`). | ||
| 3. Ask Fern, the site's AI chat, is configured under `ai-search`: `datasources` (extra sites to index), `system-prompt`, `disclaimer`, `mask-pii`. Add guidance and content sources from the Dashboard or the Ask Fern API. | ||
| 4. Run `fern docs dev` and open a page's `.md` URL to check the output. | ||
|
|
||
| ## Rules | ||
|
|
||
| - `<llms-only>` content is also hidden from Ask Fern. Don't put content there that Ask Fern needs to answer from. | ||
| - `hidden: true` and `noindex: true` pages are left out of `llms.txt`, but their `.md` URL still works. | ||
| - Keep the page directive short. It's prepended to every page. | ||
|
|
||
| ## Verify | ||
|
|
||
| - `<site>/llms.txt` lists the expected pages, and `<page>.md` shows the expected content and directive after publishing. | ||
|
|
||
| ## Reference | ||
|
|
||
| - [AI features overview](https://buildwithfern.com/learn/docs/ai-features/overview.md) | ||
| - [llms.txt](https://buildwithfern.com/learn/docs/ai-features/llms-txt.md) | ||
| - [Markdown access](https://buildwithfern.com/learn/docs/ai-features/markdown.md) | ||
| - [Agent directives](https://buildwithfern.com/learn/docs/ai-features/agent-directives.md) | ||
| - [Customize LLM output](https://buildwithfern.com/learn/docs/ai-features/customize-llm-output.md) | ||
| - [Ask Fern](https://buildwithfern.com/learn/docs/ai-features/ask-fern/overview.md) | ||
| - [MCP server](https://buildwithfern.com/learn/docs/ai-features/mcp-server.md) | ||
| - [Host agent skills](https://buildwithfern.com/learn/docs/ai-features/host-skills.md) |
37 changes: 37 additions & 0 deletions
37
fern/products/home/pages/fern-instructions/docs/analytics.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,37 @@ | ||
| --- | ||
| title: Add analytics to Fern docs | ||
| slug: fern-instructions/docs/analytics | ||
| description: Connect PostHog, Google Analytics and Tag Manager, Segment, Mixpanel, FullStory, or Intercom to a Fern docs site. | ||
| --- | ||
|
|
||
| Use this to track readers or add a support widget. | ||
|
|
||
| ## Workflow | ||
|
|
||
| 1. Ask the user which tool they use and for its public key or ID. Don't invent IDs. | ||
| 2. Add it under `analytics` (or `integrations` for support tools) in `docs.yml`, using the key names from that tool's page. For example: | ||
|
|
||
| ```yaml | ||
| analytics: | ||
| posthog: | ||
| api-key: phc_xxxxxxxx | ||
| gtm: | ||
| container-id: GTM-XXXXXXX | ||
| ``` | ||
|
|
||
| 3. Publish and confirm events arrive in the tool. | ||
|
|
||
| ## Rules | ||
|
|
||
| - Use the built-in integrations rather than adding tracking scripts through `js`. | ||
| - Fern also has built-in web analytics in the Dashboard and `llms.txt` analytics. Check whether those already answer the user's question. | ||
|
|
||
| ## Verify | ||
|
|
||
| - After publishing, page views show in the tool. The analytics events page lists what Fern sends. | ||
|
|
||
| ## Reference | ||
|
|
||
| - [Integrations overview](https://buildwithfern.com/learn/docs/integrations/overview.md) | ||
| - [PostHog](https://buildwithfern.com/learn/docs/integrations/analytics/posthog.md), [Google](https://buildwithfern.com/learn/docs/integrations/analytics/google.md), [Segment](https://buildwithfern.com/learn/docs/integrations/analytics/segment.md), [Mixpanel](https://buildwithfern.com/learn/docs/integrations/analytics/mixpanel.md), [FullStory](https://buildwithfern.com/learn/docs/integrations/analytics/fullstory.md), [Intercom](https://buildwithfern.com/learn/docs/integrations/support/intercom.md) | ||
| - [Analytics events](https://buildwithfern.com/learn/docs/integrations/analytics/events.md) |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
📝 [vale] <FernStyles.Acronyms> reported by reviewdog 🐶
'TTY' has no definition.