Skip to content
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.

Sign up for GitHub

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

docs: improve documentation build and upgrade guide #52634

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+86 −4
Open

docs: improve documentation build and upgrade guide #52634

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
90 changes: 86 additions & 4 deletions docs/contributing-to-airbyte/writing-docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,12 @@ cd docusaurus
pnpm install
```

:::important
Before making any documentation changes, always verify that you can successfully build the documentation in your environment. This helps distinguish between pre-existing issues and problems introduced by your changes.
:::

#### Development Build

To see changes as you make them in a dev build:

1. Run:
Expand All @@ -105,16 +111,45 @@ To see changes as you make them in a dev build:

2. Navigate to [http://localhost:3005/](http://localhost:3005/). Whenever you make and save changes, you will see them reflected in the server. To stop the running server, press <kbd>Ctrl</kbd>+<kbd>C</kbd> in the terminal.

To create an optimized production build that does not update automatically:
#### Production Build

1. Run:
To create an optimized production build:

1. Clear any previous builds and create a new production build:

```bash
pnpm clear && pnpm build
```

2. Review the build output carefully for:
- Broken links and anchors (common during documentation restructuring)
- Module loading warnings (these may indicate compatibility issues)
- Missing dependencies or configuration problems

3. To serve the production build locally:

```bash
pnpm build
pnpm serve
```

2. Navigate to [http://localhost:3000/](http://localhost:3000/) to see your changes. To stop the running server, press <kbd>Ctrl</kbd>+<kbd>C</kbd> in the terminal.
4. Navigate to [http://localhost:3000/](http://localhost:3000/) to verify your changes. To stop the running server, press <kbd>Ctrl</kbd>+<kbd>C</kbd> in the terminal.

#### Common Build Issues

1. **Broken Links and Anchors**
- Links must match the exact case of the target file/heading
- Anchors are generated from headings: spaces become hyphens, special characters are removed
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is true, but it's also possible to specify anchors manually. This is important when creating headings you want to link to from other places, because it prevents anchor links from breaking if a heading is rewritten later.

- Use relative paths for internal documentation links
- Always verify links work in both development and production builds

2. **Module Loading Warnings**
- CommonJS/ES Module warnings are expected and can be safely ignored
- If you see new module-related errors, verify your Node.js version matches the one in `.nvmrc`

3. **Build Performance**
- First builds may take longer due to dependency installation
- Use `pnpm clear` before `pnpm build` to ensure a clean build
- The development server (`pnpm start`) may take 1-2 minutes to initially compile
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not the right place for this information. This section is about production builds, but this information talks about a development build.


### Author content

Expand Down Expand Up @@ -256,6 +291,28 @@ The [Mermaid documentation](https://mermaid.js.org/intro) goes into more depth.

If you're adding a new file, removing a file, or moving things around, update [`docusaurus/sidebars.js`](https://github.com/airbytehq/airbyte/blob/master/docusaurus/sidebars.js) to reflect the new structure.

### Handle Broken Links

When Docusaurus reports broken links:

1. **Types of Link Issues**
- Missing files or incorrect paths
- Case sensitivity mismatches
- Incorrect anchor references
- Relative vs. absolute path issues

2. **Resolution Steps**
- Use production builds to catch all link issues
- Fix the most critical navigation paths first
- Update internal cross-references systematically
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you mean by this?

- Consider adding redirects for moved content
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clarify that this is done with the redirects.yaml file.


3. **Prevention**
- Test links in both development and production builds
- Use relative paths for internal documentation
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you mean: use relative paths when linking to content within the site. This is not internal documentation.

- Follow consistent heading case conventions
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is incorrect. Firstly, this has nothing to do with preventing broken links. Secondly, follow the guidance in the Google Developers Style Guide, as this article already specifies.

- Document any intentionally external references
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think that's necessary. We can easily scan for these.


### Add a redirect

If you're moving or renaming a page, you should add a redirect to its new location. If you're deleting a page, you should add a redirect to the most relevant new file, like a replacement topic or a parent page.
Expand All @@ -266,6 +323,31 @@ To add a redirect, open the [`docusaurus/redirects.yml`](https://github.com/airb
Your path needs a leading slash `/` to work
:::

### Handling Documentation Framework Updates

When updating core documentation dependencies (like Docusaurus):

1. **Before Starting**
- Create a complete build with current version
- Document any existing warnings or errors
- Note any custom components or plugins that might be affected

2. **During the Update**
- Update dependencies incrementally if possible
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Generally, yeah this is good practice. But upgrading the core Docusaurus library and running pnpm install will update dependencies for you. You do not need to incrementally update anything with Docusaurus unless this is a complex, major, breaking change. This is incredibly rare and Docusaurus will issue guidance for this.

- Test custom components after each major change
- Keep track of any new warnings or errors introduced
- Pay special attention to:
- Link validation changes
- Markdown parsing updates
- Plugin compatibility
- Custom component behavior

3. **After the Update**
- Run a complete production build
- Compare new warnings/errors with pre-update list
- Test documentation rendering in both development and production modes
- Verify all custom components still function correctly

### Document a code module

If you're adding a README to a code module, make sure the README has the following components:
Expand Down
Loading