diff --git a/README.md b/README.md index 4f8a897..ce3b0f0 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,10 @@ Run the following command to ensure you are using the latest version of Fern: fern upgrade ``` -Replace `plantstore` with your own organization's name. Use only alphanumeric characters, hyphens, and underscores. Do not use spaces and leave the rest of the URL (`docs.buildwithfern.com`) unchanged. +Replace `plantstore` with your own organization's name. Use only alphanumeric characters, hyphens, and underscores. + +**2. Update `docs.yml`:** +Open the `docs.yml` file and change the `instances.url` value from `plantstore` to your company name that you used for the `organization` name. **Do not use spaces and leave the rest of the URL (`docs.buildwithfern.com`) unchanged.** It should now read: @@ -81,7 +84,9 @@ Run the following command: fern generate --docs ``` -You will be prompted to log in and connect your GitHub account. +You will be prompted to log in and connect your GitHub account. + +You might also be prompted, `yes` or `no`, about if you want to proceed with generating docs and informed that you can choose between using the `--preview` flag or not. You can choose to use either `fern generate --docs` or `fern generate --docs --preview` at this time. This decision is important later, when you are making changes that might affect a production docs environment, but it won't impact your docs project now. Once the documentation is generated, you will receive the URL where your documentation is published. For example: @@ -95,12 +100,31 @@ Once the documentation is generated, you will receive the URL where your documen Preview your documentation locally. Run ​`fern docs dev`​ to access your docs on your local server at port 3000, hot-reloading as you edit your markdown and OpenAPI files. [Learn more](https://buildwithfern.com/learn/docs/getting-started/development?utm_source=github&utm_medium=readme&utm_campaign=docs-starter-openapi&utm_content=step6) or [watch a 10-second demo](https://www.loom.com/share/0a4658bd78cb45d5a9519277852c7a24?sid=3ce69ad0-bfdb-4fa1-9abf-2f4366d084b9). -### Step 6: Customize your documentation +### Step 6: Preview your documentation +You can generate documentation previews -You must run `fern generate --docs` after any modifications to re-generate and publish your documentation site. +#### Generate previews from CLI To preview updates to your documentation before publishing changes, run `fern generate --docs --preview`. +#### Configure PR previews + +Your quickstart Fern project also includes GitHub Actions, including an action that enables generating previews in PRs. You don't need to update anything in the GitHub actions, but you do need to create a `FERN_TOKEN` auth token to enable them. + +1. Open your GitHub repository and [create a new repository secret](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-repository). +2. For the **Name**, use `FERN_TOKEN`. +3. In your local terminal, run [`fern token`](https://buildwithfern.com/learn/cli-api-reference/cli-reference/commands#detailed-command-documentation) to generate an auth token value. +4. Copy the output from your terminal, and paste in GitHub as the **Value**. +5. Save your new secret. + +You might need to re-run preview builds for any PRs that were opened before you configured the `FERN_TOKEN`. + +For more information about built-in automation for previews and the `preview-docs.yml` GitHub action, see the [Previewing changes in a PR](https://buildwithfern.com/learn/docs/preview-publish/previewing-changes-in-a-pr#usage-in-github-actions) Fern docs. + +### Step 7: Customize your documentation + +You must run `fern generate --docs` after any modifications to re-generate and publish your documentation site. + To use your own OpenAPI specification file or to update the existing one: - Update or replace the OpenAPI specification file in the `openapi/` folder.