fix: resolve mkdocs strict mode build failures #42

tommcd · 2025-11-19T18:30:20Z

Fixed all broken links that were causing --strict mode to fail:

docs/index.md: Changed trailing slashes to .md extensions
- getting-started/installation/ → installation.md
- getting-started/quick-start/ → quick-start.md
- api/core-integration/ → core-integration.md
- guides/adding-new-interface/ → adding-new-interface.md
docs/api/core-integration.md: Removed broken link to non-existent core.md file
docs/api/lsp.md: Removed broken links to files outside docs directory
- Removed link to extensions/doctk-outliner/README.md
- Removed link to CONTRIBUTING.md
docs/guides/*.md: Changed source file links from markdown links to plain text with backticks (files outside docs directory)
- src/doctk/cli.py
- src/doctk/dsl/repl.py
- src/doctk/dsl/executor.py
- tests/unit/test_structure_operations.py

Build now succeeds with --strict mode on GitHub Actions.

Fixed all broken links that were causing --strict mode to fail: 1. docs/index.md: Changed trailing slashes to .md extensions - getting-started/installation/ → installation.md - getting-started/quick-start/ → quick-start.md - api/core-integration/ → core-integration.md - guides/adding-new-interface/ → adding-new-interface.md 2. docs/api/core-integration.md: Removed broken link to non-existent core.md file 3. docs/api/lsp.md: Removed broken links to files outside docs directory - Removed link to extensions/doctk-outliner/README.md - Removed link to CONTRIBUTING.md 4. docs/guides/*.md: Changed source file links from markdown links to plain text with backticks (files outside docs directory) - src/doctk/cli.py - src/doctk/dsl/repl.py - src/doctk/dsl/executor.py - tests/unit/test_structure_operations.py Build now succeeds with --strict mode on GitHub Actions.

gemini-code-assist · 2025-11-19T18:30:35Z

Summary of Changes

Hello @tommcd, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses and resolves several documentation build failures encountered when running mkdocs in strict mode. The changes primarily involve correcting various types of broken links, including updating internal path formats, removing references to non-existent files, and reformatting links to external source code files. This ensures the documentation builds cleanly and accurately reflects the project structure.

Highlights

Link Formatting: Corrected internal documentation links in docs/index.md by changing trailing slashes to .md extensions for proper resolution.
Broken Link Removal: Removed non-existent and external file links from docs/api/core-integration.md and docs/api/lsp.md to prevent build failures.
External Source File Links: Updated links in docs/guides/*.md from markdown-formatted links to plain text with backticks for external source files, ensuring mkdocs --strict compatibility.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request successfully addresses broken links in the documentation to enable a strict mkdocs build. The approach of converting external links to plain text and fixing internal link formats is correct. However, I've identified a few areas where the changes are inconsistent, and some potentially valuable links have been removed instead of being fixed. My review includes suggestions to improve consistency and restore these useful cross-references.

tommcd · 2025-11-19T18:55:26Z

/gemini review

tommcd · 2025-11-19T18:56:02Z

@codex review

gemini-code-assist

Code Review

This pull request does a good job of fixing broken links in the documentation to resolve mkdocs strict mode build failures. The approach of converting links to external files into plain text paths is sound.

I've added a few suggestions:

One comment points out an inconsistent link fix that was likely missed.
Two other comments suggest preserving useful links to design documents by converting them to plain text paths instead of removing them entirely. This would retain valuable information for readers.

Additionally, I noticed that docs/api/dsl.md also contains a link to ../design/02-pluggable-architecture.md. If links to the design directory are indeed causing build failures, this one might need to be fixed as well. Since this file is not part of the PR, I'm mentioning it here for your consideration.

Overall, these are minor points and the PR is on the right track to solve the build issue.

gemini-code-assist · 2025-11-19T18:57:43Z

docs/api/core-integration.md

 ## See Also

- [Pluggable Architecture Design](../design/02-pluggable-architecture.md)
 - [DSL API Reference](./dsl.md)
 - [LSP API Reference](./lsp.md)


While removing the broken link to core.md is correct, the link to 02-pluggable-architecture.md pointed to an existing file and was a useful reference. Instead of removing it, you could convert it to a plain text path to fix the build error while preserving the information.

Suggested change

## See Also

- [Pluggable Architecture Design](../design/02-pluggable-architecture.md)

- [DSL API Reference](./dsl.md)

- [LSP API Reference](./lsp.md)

## See Also

- Pluggable Architecture Design: `docs/design/02-pluggable-architecture.md`

- [DSL API Reference](./dsl.md)

- [LSP API Reference](./lsp.md)

docs/guides/adding-new-interface.md

gemini-code-assist · 2025-11-19T18:57:43Z

docs/guides/adding-new-interface.md

 - [Core Integration API Reference](../api/core-integration.md)
- [Pluggable Architecture Design](../design/02-pluggable-architecture.md)
- [VS Code Extension Source](../../extensions/doctk-outliner/)
- [REPL Source](../../src/doctk/dsl/repl.py)
- [Architecture Decisions](../design/03-core-integration-decisions.md)
+- VS Code Extension Source: `extensions/doctk-outliner/`
+- REPL Source: `src/doctk/dsl/repl.py`


Instead of removing the links to the design documents, you could convert them to plain text paths. This preserves the useful references for readers while fixing the build.

Suggested change

- [Core Integration API Reference](../api/core-integration.md)

- [Pluggable Architecture Design](../design/02-pluggable-architecture.md)

- [VS Code Extension Source](../../extensions/doctk-outliner/)

- [REPL Source](../../src/doctk/dsl/repl.py)

- [Architecture Decisions](../design/03-core-integration-decisions.md)

- VS Code Extension Source: `extensions/doctk-outliner/`

- REPL Source: `src/doctk/dsl/repl.py`

- [Core Integration API Reference](../api/core-integration.md)

- Pluggable Architecture Design: `docs/design/02-pluggable-architecture.md`

- Architecture Decisions: `docs/design/03-core-integration-decisions.md`

- VS Code Extension Source: `extensions/doctk-outliner/`

- REPL Source: `src/doctk/dsl/repl.py`

Copilot

Pull Request Overview

This PR fixes mkdocs strict mode build failures by correcting broken documentation links. The main issue was that mkdocs strict mode fails when links point to non-existent files or files outside the docs directory.

Key changes:

Updated internal documentation links to use .md extensions instead of trailing slashes
Removed links to excluded design documents (design/ directory is excluded in mkdocs.yml)
Converted links to source code files outside docs/ into plain text references with backticks
Removed broken reference to non-existent core.md file

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/index.md	Changed internal doc links from trailing slash format to .md extensions for Getting Started and API sections
docs/guides/extending-dsl.md	Converted source code links (executor.py, test files) to plain text references
docs/guides/adding-new-interface.md	Converted source code links to plain text and removed excluded design doc links
docs/api/lsp.md	Removed links to files outside docs directory (VS Code extension README, CONTRIBUTING.md) and associated section
docs/api/core-integration.md	Removed links to excluded design docs and non-existent core.md file

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-11-19T18:58:20Z

docs/guides/adding-new-interface.md


 ### Example Interfaces

 - **VS Code Extension**: TypeScript extension with JSON-RPC bridge ([source](../../extensions/doctk-outliner/))


This link to ../../extensions/doctk-outliner/ points to a directory outside the docs folder and should be converted to plain text format for consistency with the other source code references in this PR. Change it to: - **VS Code Extension**: TypeScript extension with JSON-RPC bridge (\extensions/doctk-outliner/`)`

Suggested change

- **VS Code Extension**: TypeScript extension with JSON-RPC bridge ([source](../../extensions/doctk-outliner/))

- **VS Code Extension**: TypeScript extension with JSON-RPC bridge (`extensions/doctk-outliner/`)

chatgpt-codex-connector · 2025-11-19T18:58:21Z

Codex Review: Didn't find any major issues. Keep it up!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

gemini-code-assist bot reviewed Nov 19, 2025

View reviewed changes

tommcd requested a review from Copilot November 19, 2025 18:55

Copilot started reviewing on behalf of tommcd November 19, 2025 18:56 View session

gemini-code-assist bot reviewed Nov 19, 2025

View reviewed changes

Copilot finished reviewing on behalf of tommcd November 19, 2025 18:58

Copilot AI reviewed Nov 19, 2025

View reviewed changes

Update docs/guides/adding-new-interface.md

393785f

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

tommcd merged commit b3b6956 into master Nov 19, 2025
3 checks passed

tommcd deleted the claude/implement-next-prompt-01Aox3z4pAH98YzA3pbHtxgd branch November 22, 2025 13:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix: resolve mkdocs strict mode build failures #42

fix: resolve mkdocs strict mode build failures #42

Uh oh!

tommcd commented Nov 19, 2025

Uh oh!

gemini-code-assist bot commented Nov 19, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

tommcd commented Nov 19, 2025

Uh oh!

tommcd commented Nov 19, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Nov 19, 2025

Uh oh!

Uh oh!

gemini-code-assist bot Nov 19, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Nov 19, 2025

Uh oh!

chatgpt-codex-connector bot commented Nov 19, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		### Example Interfaces

		- VS Code Extension: TypeScript extension with JSON-RPC bridge ([source](../../extensions/doctk-outliner/))

Uh oh!

fix: resolve mkdocs strict mode build failures #42

fix: resolve mkdocs strict mode build failures #42

Uh oh!

Conversation

tommcd commented Nov 19, 2025

Uh oh!

gemini-code-assist bot commented Nov 19, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

tommcd commented Nov 19, 2025

Uh oh!

tommcd commented Nov 19, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gemini-code-assist bot Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot commented Nov 19, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants