Skip to content

Update style-guide.md for nested includes #207

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

Merged
merged 5 commits into from
Feb 25, 2025
Merged

Update style-guide.md for nested includes #207

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c763341
Update style-guide.md for nested includes
mjang Feb 19, 2025
7448502
Merge branch 'main' into fix-clarify-includes-style-guide
ADubhlaoich Feb 19, 2025
3100776
Update templates/style-guide.md
mjang Feb 19, 2025
2e3f041
Merge branch 'main' into fix-clarify-includes-style-guide
ADubhlaoich Feb 21, 2025
d18c45c
Merge branch 'main' into fix-clarify-includes-style-guide
ADubhlaoich Feb 25, 2025
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
3 changes: 2 additions & 1 deletion templates/style-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -449,7 +449,7 @@ To make sure includes are effective and easy to maintain, follow these practices
- **Keep includes small and modular**: Write narrowly scoped snippets to maximize flexibility and reuse.
- **Avoid branded product names in includes**: Use the full product name (e.g., "NGINX Instance Manager"), but avoid including the branded version (e.g., "F5 NGINX Instance Manager"). The branded name is required only on the first mention in a document; this is a context-specific rule. Includes, however, are designed to be context-agnostic—they should not rely on or assume any prior content—so including the branded name could repeat information unnecessarily in locations where it has already been introduced.
- **Don't include headers**: Avoid adding H2 or other headers inside includes. These headers won't appear in the document's table of contents (TOC) and may not fit well with the surrounding content hierarchy. Add headers directly in the document instead.
- **Avoid nesting includes**: Don't place an include inside another include. While technically possible, it complicates reviews and maintenance. Use a flat structure for simplicity.
- **Avoid nesting includes**: If there’s another way to achieve the same outcome, avoid nesting includes. While technically possible, it complicates reviews and maintenance. Use a flat structure for simplicity.
- **Don't start documents with includes**: The opening of a document is usually the introduction, which explains its purpose. Includes are reused text, so starting multiple documents with identical content could look odd, especially in search results.

## Guidelines for command-line operations
Expand Down Expand Up @@ -503,6 +503,7 @@ this style guide over time. This guide uses the Major.Minor.Patch

| Edition | Date | Lead Author(s) | Comments |
|---------|---------------|----------------|-------------------------------------------------------|
| 1.10 | February 19, 2025 | Mike Jang | Clarify use of nested includes. |
| 1.9 | December 10, 2024 | Mike Jang | Specify the use of "license" when writing about the JWT token associated with licensed versions of NGINX. |
| 1.8 | December 4, 2024 | Jon Torre | Clarify that heading text must not contain a link to other pages. |
| 1.7 | November 20, 2024 | Mike Jang | Specify "includes" must be in at leat two locations. |
Expand Down
Loading