nrwl
Update formatting of agent rules documentation
Markdown documents should only have one h1 header, it is pretty unlikely that an existing agents config does not already have one, switching to h2 instead should make most linters happy.
In theory you could make this a little smarter by checking beforehand..
I am also considering adding a line akin to
Never use `nx graph` command - This spawns a web server that you don't have access to.
Use the `nx_visualize_graph` tool or other nx tools instead.
since mine keeps doing that. thoughts?
Current Behavior
The header is inserted as an h1
Expected Behavior
The header is inserted as an h2
Related Issue(s)
Fixes #
Deploy request for nx-docs pending review.
Visit the deploys page to approve it
| Name | Link |
|---|---|
| Latest commit | eb537ed6611d2d74ae986243922df779a08069f8 |
![netlify[bot] avatar](https://avatars.githubusercontent.com/in/13473?v=4 "Published by a pub.dev verified publisher"){kind=small}
The latest updates on your projects. Learn more about Vercel for GitHub.
| Project | Deployment | Preview | Updated (UTC) |
|---|---|---|---|
| nx-dev |  Ready |
Preview | Dec 8, 2025 9:19pm |
![vercel[bot] avatar](https://avatars.githubusercontent.com/in/8329?v=4 "Published by a pub.dev verified publisher"){kind=small}
I see what you mean... we decided for an h1 originally because then we can make sure that we're not messing with anyone's layout by nesting something where they don't want to. I wasn't aware of this best practice to only ever use one h1 though, what kind of markdown linter are you using? Does it have that preconfigured? I'm open to changing this in general though.
I see what you mean... we decided for an h1 originally because then we can make sure that we're not messing with anyone's layout by nesting something where they don't want to. I wasn't aware of this best practice to only ever use one h1 though, what kind of markdown linter are you using? Does it have that preconfigured? I'm open to changing this in general though.
I'm on https://github.com/DavidAnson/markdownlint-cli2 (or rather the tooling around it) the rule is https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md025.md
there are also spacing issues, currently it has two blank links before and after the snippet, which also triggers linters. so if we want to make it smarter it should
- check if it is the only content of the file, if yes, no space before, use an h1 and then 1 or 0 empty lines after
- if it is not the only content, use h2 with one space before and one after
I now addressed that with an additional commit so it now dynamically adjusts spacing and header