This is an automated email from the ASF dual-hosted git repository.
GitToTheHub pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cordova-docs.git
The following commit(s) were added to refs/heads/master by this push:
new 6dc8d6bf3c docs: clarify heading capitalization and link style
guidance (#1545)
6dc8d6bf3c is described below
commit 6dc8d6bf3cbb3c20e3e5694c8908b239ff6f8aa0
Author: Manuel Beck <[email protected]>
AuthorDate: Tue Nov 3 12:42:43 2026 +0100
docs: clarify heading capitalization and link style guidance (#1545)
The Editorial Style Sheet already mentions heading capitalization, but
omits articles and first/last-word handling. Contributors can also miss the
guide when submitting documentation changes.
Expand the existing heading guidance with major/minor word rules, examples,
hyphenation, and product/API spelling. Link APA guidance for further examples.
Add a visible documentation-style checklist item linking to the existing guide
in the PR template rather than duplicating the rules.
The first/last-word convention follows the community feedback; the APA link
provides examples of major and minor words.
Generated-by: OpenAI Codex (GPT-6.1 Sol)
---
.github/PULL_REQUEST_TEMPLATE.md | 1 +
doc/docs-STYLEGUIDE.md | 19 ++++++++++++++-----
2 files changed, 15 insertions(+), 5 deletions(-)
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 1a754622cb..54821a25d9 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -33,3 +33,4 @@ Thanks!
- [ ] Commit is prefixed with `(platform)` if this change only applies to one
platform (e.g. `(android)`)
- [ ] If this Pull Request resolves an issue, I linked to the issue in the
text above (and used the correct [keyword to close issues using
keywords](https://help.github.com/articles/closing-issues-using-keywords/))
- [ ] I've updated the documentation if necessary
+- [ ] Documentation changes follow the [Editorial Style
Sheet](https://github.com/apache/cordova-docs/blob/master/doc/docs-STYLEGUIDE.md#structure-and-flow),
including heading capitalization (if applicable)
diff --git a/doc/docs-STYLEGUIDE.md b/doc/docs-STYLEGUIDE.md
index abf99baf2a..7721cc3079 100644
--- a/doc/docs-STYLEGUIDE.md
+++ b/doc/docs-STYLEGUIDE.md
@@ -68,11 +68,20 @@ help identify them in Markdown.
is, if one is task-based and reads "Adding a Platform," the other
should be "Developing for Android" rather than "Android Development"
-* __Heading Content__: In reference doc, preserve case in titles and
- headings. In guide doc: Initial Cap Words in Headings, Except for
- Short Prepositions or Conjunctions. Also Init-Cap Around Hyphens. No
- punctuation at the end of a heading, and avoid punctuation within
- headings. Do not prefix headings with numbers.
+* __Heading Content__: In reference doc, preserve the case of API names
+ and identifiers in titles and headings. In guide doc, use title case:
+ capitalize the first and last words, nouns, pronouns, verbs, adjectives,
+ adverbs, and words of four or more letters. Lowercase articles ("a",
+ "an", "the"), short conjunctions ("and", "but", "or"), and short
+ prepositions ("at", "for", "in", "of", "to") unless they are the first
+ or last word. Capitalize both parts of hyphenated major words, as in
+ "Self-Report". Preserve the official spelling of product names such as
+ "macOS" and "Node.js". Examples: "Installing a Development Environment",
+ "Building and Deploying the Website", and "Verify the Setup". See the
+ [APA title case
guidance](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case)
+ for more examples of major and minor words. No punctuation at the end
+ of a heading, and avoid punctuation within headings. Do not prefix
+ headings with numbers.
grep -hr '^#' * | sed 's/^#*//g' | grep '[^A-Za-z0-9 ]'
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
