fix: move non-interactive-installation into how-to directory #1587
Conversation
Fixes bmad-code-org#1564. The page was orphaned from the Starlight sidebar because it lived at docs/ root instead of docs/how-to/, which is the autogenerated sidebar directory. Also fixes the broken link in install-bmad.md and updates the README reference.
|
@coderabbitai review |
🤖 Augment PR SummarySummary: Relocates the Non-Interactive Installation guide into 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
📝 WalkthroughWalkthroughThis pull request updates documentation links across two files to reflect the relocation of non-interactive installation documentation from Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
README.md (1)
33-39:⚠️ Potential issue | 🟡 MinorSection context doesn't match the link description.
Lines 33-37 show a command example with
--directory,--modules,--tools, and--yesflags, followed by line 39 directing users to "Non-Interactive Installation Guide" for "all available options."However, the section header on line 33 says "Non-Interactive Installation" but the description emphasizes "For CI/CD pipelines or automated deployments." This creates semantic confusion similar to the issue in install-bmad.md. Is this about:
- Non-interactive mode (no prompts via
--yesflag)?- CI/CD automation?
- All available CLI options?
The framing should be clearer and consistent. If it's about CLI options, say "CLI Options Guide." If it's specifically about non-interactive mode, keep the terminology consistent between description and link text.
🤖 Fix all issues with AI agents
In `@docs/how-to/install-bmad.md`:
- Line 8: The link text uses "automated or scripted installations" which
misaligns with the target doc title and intent; change the phrase back to
"Non-Interactive Installation" so the sentence reads e.g. "For non-interactive
installation, see the [Non-Interactive
Installation](/docs/how-to/non-interactive-installation.md) guide." Update the
visible link text and surrounding wording in the line containing that link to
match the document title and emphasize running the installer with flags to skip
prompts (maintain the same href).
- Line 8: Update inline Markdown links to remove the .md extension so they match
Starlight routing: replace occurrences like
"/docs/how-to/non-interactive-installation.md" with
"/docs/how-to/non-interactive-installation" (and similarly change
"/docs/tutorials/getting-started.md" and "/docs/reference/workflow-map.md" to
their extensionless counterparts). Search for link strings containing ".md"
across docs and standardize them to the extensionless path, and then verify the
Starlight config/redirects or any rehype plugin handles legacy .md URLs; if not,
add redirects or adjust the links as described.
In `@README.md`:
- Line 39: README.md and docs/how-to/install-bmad.md use inconsistent link
formats for the same target (README uses
"docs/how-to/non-interactive-installation.md" while install-bmad.md uses
"/docs/how-to/non-interactive-installation.md"); pick the repository convention
(prefer relative paths without leading slash from root) and update all
references to the same format—specifically edit the link text in README.md and
docs/how-to/install-bmad.md to use the agreed path (e.g.,
"docs/how-to/non-interactive-installation.md") so both files reference the
identical link format.
- Line 39: Update the inconsistent relative link in README.md so it matches the
other documentation links by using the absolute URL for the non-interactive
installation page (i.e., replace "docs/how-to/non-interactive-installation.md"
with "http://docs.bmad-method.org/how-to/non-interactive-installation.html" or
the canonical absolute docs URL used elsewhere in the README) to preserve a
consistent documentation entry point.
- Line 39: Replace the relative Markdown link on line 39 pointing to
"docs/how-to/non-interactive-installation.md" with the external docs site URL
used elsewhere; update the link target to
"http://docs.bmad-method.org/how-to/non-interactive-installation/" so the README
uses the same external documentation pattern as the other links (e.g., those
pointing to http://docs.bmad-method.org/how-to/upgrade-to-v6/).
🧹 Nitpick comments (1)
docs/how-to/install-bmad.md (1)
8-8: Link format inconsistency within the same file.Line 8 uses an absolute path starting with
/docs/, but this creates an inconsistent pattern. Since this file is already indocs/how-to/, a relative link like./non-interactive-installationwould be clearer and more maintainable. Starlight should resolve relative links correctly within the same directory.Compare with line 84 which also uses
/docs/how-to/get-answers-about-bmad.md— while consistent in format, both should potentially use relative paths for files in the same directory.♻️ Consider using a relative path
-For automated or scripted installations, see the [Non-Interactive Installation](/docs/how-to/non-interactive-installation.md) guide. +For automated or scripted installations, see the [Non-Interactive Installation](./non-interactive-installation) guide.Note: Removed
.mdextension assuming Starlight convention.
| Use the `npx bmad-method install` command to set up BMad in your project with your choice of modules and AI tools. | ||
|
|
||
| If you want to use a non interactive installer and provide all install options on the command line, [this guide](/docs/non-interactive-installation.md). | ||
| For automated or scripted installations, see the [Non-Interactive Installation](/docs/how-to/non-interactive-installation.md) guide. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check the content of the target file to verify appropriate terminology
if [ -f "docs/how-to/non-interactive-installation.md" ]; then
echo "=== File title and first 30 lines ==="
head -n 30 docs/how-to/non-interactive-installation.md
echo -e "\n=== Check for automation/scripting keywords ==="
rg -i 'automat|script|ci.*cd|pipeline|ci|cd' docs/how-to/non-interactive-installation.md
echo -e "\n=== Check for non-interactive keywords ==="
rg -i 'non-interactive|--yes|prompt|interactiv' docs/how-to/non-interactive-installation.md
else
echo "File not found: docs/how-to/non-interactive-installation.md"
echo "Checking for similar files..."
find . -name "*non-interactive*" -o -name "*install*" | head -20
fiRepository: bmad-code-org/BMAD-METHOD
Length of output: 2851
Terminology change reduces clarity and may mislead users.
The line now references "automated or scripted installations," but the target document is titled "Non-Interactive Installation." While the document does cover CI/CD and scripting scenarios, these are secondary use cases, not the primary mechanism. The core concept is non-interactive installation—running the installer with flags to skip prompts. A user specifically seeking non-interactive installation guidance may not recognize themselves in "automated or scripted installations," while a user needing CI/CD guidance might be puzzled to land on a document primarily about non-interactive behavior.
Revert to referencing "non-interactive installation" to match the document's actual title and primary mechanism.
🤖 Prompt for AI Agents
In `@docs/how-to/install-bmad.md` at line 8, The link text uses "automated or
scripted installations" which misaligns with the target doc title and intent;
change the phrase back to "Non-Interactive Installation" so the sentence reads
e.g. "For non-interactive installation, see the [Non-Interactive
Installation](/docs/how-to/non-interactive-installation.md) guide." Update the
visible link text and surrounding wording in the line containing that link to
match the document title and emphasize running the installer with flags to skip
prompts (maintain the same href).
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if target file exists
echo "=== Checking target file existence ==="
if [ -f "docs/how-to/non-interactive-installation.md" ]; then
echo "✓ Target file exists: docs/how-to/non-interactive-installation.md"
else
echo "✗ MISSING: docs/how-to/non-interactive-installation.md"
fi
# Check if the file referenced in the review exists
echo -e "\n=== Checking if install-bmad.md exists ==="
if [ -f "docs/how-to/install-bmad.md" ]; then
echo "✓ File exists: docs/how-to/install-bmad.md"
else
echo "✗ MISSING: docs/how-to/install-bmad.md"
fi
# Find other markdown links in the docs directory to understand the convention
echo -e "\n=== Links with .md extension in docs/how-to/install-bmad.md ==="
rg '\[.*\]\(/docs/[^)]+\.md\)' docs/how-to/install-bmad.md
echo -e "\n=== All links in docs/how-to/install-bmad.md ==="
rg '\[.*\]\([^)]+\)' docs/how-to/install-bmad.md
# Check for Starlight config to understand routing
echo -e "\n=== Looking for Starlight config ==="
fd -e "astro.config" -e "starlight.config" -e "sidebar"
# Check what link formats are used across the docs directory
echo -e "\n=== Sample links from other docs ==="
rg '\[.*\]\(/docs/[^)]+\)' docs/ | head -20Repository: bmad-code-org/BMAD-METHOD
Length of output: 2512
🌐 Web query:
Starlight documentation links .md extension routing
💡 Result:
Starlight pages do not keep the .md extension in the URL. Every Markdown/MDX/Markdoc file in src/content/docs/ becomes a route based on its path/filename (e.g. src/content/docs/guide.md → /guide/). So links in your docs should target the route (e.g. /guide/), not ./guide.md. [1]
If you already have lots of *.md links, you have two common fixes:
-
Rewrite relative
.mdlinks at build time (recommended for large doc sets)
Use a rehype plugin that converts./other-page.md→/other-page(preserving?query/#hash). Example:astro-rehype-relative-markdown-links. [3] -
Add redirects for
.mdURLs
Inastro.config.mjs, configure redirects like'/guide.md': '/guide/'(works across dev/prod; static builds use a client-side meta refresh). [2]
Sources:
[1] Starlight file-based routing (src/content/docs/ → pages) — https://starlight.astro.build/manual-setup/
[2] Astro configured redirects (redirects in astro.config) — https://docs.astro.build/en/guides/routing/
[3] Plugin that rewrites relative .md links — https://www.npmjs.com/package/astro-rehype-relative-markdown-links
Link format inconsistent with Starlight routing conventions.
The link uses /docs/how-to/non-interactive-installation.md with a .md extension. Starlight routes do not include the .md extension in URLs — a file like docs/how-to/non-interactive-installation.md should be linked as /docs/how-to/non-interactive-installation (without .md). This format issue affects multiple links throughout the repository (docs/tutorials/getting-started.md, /docs/reference/workflow-map.md, etc. all use the same pattern).
Verify that the project's Starlight configuration handles .md URLs via redirects or a rehype plugin; otherwise, standardize links to extensionless format.
🤖 Prompt for AI Agents
In `@docs/how-to/install-bmad.md` at line 8, Update inline Markdown links to
remove the .md extension so they match Starlight routing: replace occurrences
like "/docs/how-to/non-interactive-installation.md" with
"/docs/how-to/non-interactive-installation" (and similarly change
"/docs/tutorials/getting-started.md" and "/docs/reference/workflow-map.md" to
their extensionless counterparts). Search for link strings containing ".md"
across docs and standardize them to the extensionless path, and then verify the
Starlight config/redirects or any rehype plugin handles legacy .md URLs; if not,
add redirects or adjust the links as described.
| ``` | ||
|
|
||
| See [Non-Interactive Installation Guide](docs/non-interactive-installation.md) for all available options. | ||
| See [Non-Interactive Installation Guide](docs/how-to/non-interactive-installation.md) for all available options. |
There was a problem hiding this comment.
Link format inconsistency between files in this PR.
README.md uses a relative path docs/how-to/non-interactive-installation.md (no leading slash), while docs/how-to/install-bmad.md line 8 uses an absolute path /docs/how-to/non-interactive-installation.md (with leading slash). These are different link formats pointing to the same file.
This inconsistency suggests a lack of coordination about the correct link format. Which convention is correct for this repository? The difference matters:
- From README.md (root): relative
docs/...is correct - From docs/how-to/install-bmad.md: absolute
/docs/...or relative./...could work depending on Starlight's config
Standardize the approach across all updated references.
🤖 Prompt for AI Agents
In `@README.md` at line 39, README.md and docs/how-to/install-bmad.md use
inconsistent link formats for the same target (README uses
"docs/how-to/non-interactive-installation.md" while install-bmad.md uses
"/docs/how-to/non-interactive-installation.md"); pick the repository convention
(prefer relative paths without leading slash from root) and update all
references to the same format—specifically edit the link text in README.md and
docs/how-to/install-bmad.md to use the agreed path (e.g.,
"docs/how-to/non-interactive-installation.md") so both files reference the
identical link format.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify the relative path works from README location and check rendering context
# Verify file exists at relative path from repository root
if [ -f "docs/how-to/non-interactive-installation.md" ]; then
echo "✓ File exists at: docs/how-to/non-interactive-installation.md"
echo -e "\n=== First 15 lines (check for frontmatter) ==="
head -n 15 docs/how-to/non-interactive-installation.md
else
echo "✗ MISSING: docs/how-to/non-interactive-installation.md"
fi
# Check other doc links in README to understand the pattern
echo -e "\n=== Other documentation links in README ==="
rg -n '\[.*\]\(.*doc.*\)' README.md | head -n 20Repository: bmad-code-org/BMAD-METHOD
Length of output: 1459
Inconsistent documentation link format.
The relative link to docs/how-to/non-interactive-installation.md contradicts the documentation linking pattern used throughout the README. All other documentation references (lines 70, 117, 120, 121) use absolute URLs pointing to http://docs.bmad-method.org/..., providing a consistent entry point to the official docs site. This relative link breaks that pattern and points readers directly to the GitHub file instead, creating a fragmented documentation experience.
Standardize this link to use the absolute URL format consistent with the rest of the README, or explain why this resource is served differently.
🤖 Prompt for AI Agents
In `@README.md` at line 39, Update the inconsistent relative link in README.md so
it matches the other documentation links by using the absolute URL for the
non-interactive installation page (i.e., replace
"docs/how-to/non-interactive-installation.md" with
"http://docs.bmad-method.org/how-to/non-interactive-installation.html" or the
canonical absolute docs URL used elsewhere in the README) to preserve a
consistent documentation entry point.
🧩 Analysis chain
🏁 Script executed:
git ls-files | grep -i readmeRepository: bmad-code-org/BMAD-METHOD
Length of output: 283
🏁 Script executed:
cat -n README.md | sed -n '35,45p'Repository: bmad-code-org/BMAD-METHOD
Length of output: 681
🏁 Script executed:
cat -n README.md | sed -n '115,125p'Repository: bmad-code-org/BMAD-METHOD
Length of output: 764
🏁 Script executed:
web_search
Does the BMad documentation site at docs.bmad-method.org publish the non-interactive installation guide?Repository: bmad-code-org/BMAD-METHOD
Length of output: 162
🏁 Script executed:
find . -name "non-interactive-installation.md" -type fRepository: bmad-code-org/BMAD-METHOD
Length of output: 114
🏁 Script executed:
web_search
Does docs.bmad-method.org host non-interactive installation guide at /how-to/non-interactive-installation/Repository: bmad-code-org/BMAD-METHOD
Length of output: 162
🌐 Web query:
docs.bmad-method.org how-to non-interactive installation
💡 Result:
BMAD supports non-interactive installation by passing install choices as CLI flags. [1]
Fully non-interactive (no prompts)
npx bmad-method install \
--directory /path/to/project \
--modules bmm,bmb \
--tools claude-code,cursor \
--user-name "John Doe" \
--communication-language English \
--document-output-language English \
--output-folder _bmad-output[1]
Quick non-interactive (accept defaults)
npx bmad-method install --yes[1]
Install without IDE/tool integration
npx bmad-method install --directory ~/myapp --modules bmm --tools none[1]
Useful flags (from the docs)
--directory,--modules,--tools(usenoneto skip),--custom-content,--action- Core config:
--user-name,--communication-language,--document-output-language,--output-folder - Other:
-y/--yes,-d/--debug
[1]
Actions for existing installs
npx bmad-method install --action quick-updateActions: install, update, quick-update, compile-agents. [1]
Reference install command (interactive default):
npx bmad-method install[2]
Sources: [1] BMAD “Non-Interactive Installation” (in llms-full.txt) ; [2] “How to Install BMad” docs.
Update line 39 link to match the external documentation URL pattern used elsewhere in README.
The README uses two inconsistent link strategies:
- Line 39: Relative repository path
docs/how-to/non-interactive-installation.md - Lines 117, 120-121: External URLs to
http://docs.bmad-method.org/(e.g.,http://docs.bmad-method.org/how-to/upgrade-to-v6/)
Users viewing the README on GitHub or npm will see line 39 pointing to a raw .md file instead of the rendered documentation. Change to http://docs.bmad-method.org/how-to/non-interactive-installation/ to match the established pattern.
🤖 Prompt for AI Agents
In `@README.md` at line 39, Replace the relative Markdown link on line 39 pointing
to "docs/how-to/non-interactive-installation.md" with the external docs site URL
used elsewhere; update the link target to
"http://docs.bmad-method.org/how-to/non-interactive-installation/" so the README
uses the same external documentation pattern as the other links (e.g., those
pointing to http://docs.bmad-method.org/how-to/upgrade-to-v6/).
|
similar changes included in #1578 |
2 participants
Fixes #1564.
Moves
docs/non-interactive-installation.mdintodocs/how-to/so the Starlight sidebar picks it up viaautogenerate. Updates the cross-references ininstall-bmad.mdandREADME.md.Note: the second item in #1564 (
downloads.md) was already removed by PR #1577.