Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

feat: Replace existing archetypes with three new discrete types #97

Merged
merged 1 commit into from
Nov 26, 2024

Conversation

ADubhlaoich
Copy link
Contributor

@ADubhlaoich ADubhlaoich commented Nov 25, 2024

Proposed changes

NGINX documentation broadly follows the Diataxis model, and we have specific conventions around certain types of documents.

This commit pares the exisiting Hugo archetype down to three that are closely related: how-to, concept and tutorial. Outside of providing page-specific information architecture, these templates include our updated frontmatter formatting and parameters, and inline guidance on how we prefer to use Markdown formatting and Hugo shortcodes.

Checklist

Before creating a PR, run through this checklist and mark each as complete.

  • I have read the CONTRIBUTING document
  • If applicable, I have added tests that prove my fix is effective or that my feature works
  • If applicable, I have checked that any relevant tests pass after adding my changes
  • I have updated any relevant documentation (README.md and CHANGELOG.md)

NGINX documentation broadly follows the Diataxis model, and we have
specific conventions around certain types of documents.

This commit pares the exisiting Hugo archetype down to three that are
closely related: how-to, concept and tutorial. Outside of providing
page-specific information architecture, these templates include our
updated frontmatter formatting and parameter, and inline guidance
on how we prefer to use Markdown formatting and Hugo shortcodes.

There will be additional work of this nature in the future, once more
specialised content types have been identified and consensus has been
reached on what their precise style should be.
@mjang
Copy link
Contributor

mjang commented Nov 25, 2024

As a next step, it might be worth working with https://github.com/hawkeyexl/doc-structure-lint, which can supposedly verify rules for each document type. (I tried it with an earlier version, but did not test Manny Silva's fix)

@ADubhlaoich
Copy link
Contributor Author

Automation of template checks is a bit farther in the future as we still need to figure out details for other document types which have been inconsistent across different products, like release notes.

Gitlab has a few lightweight shell scripts for Markdown linting which could probably be turned into part of an action.

@ADubhlaoich ADubhlaoich merged commit 506e73e into main Nov 26, 2024
@ADubhlaoich ADubhlaoich deleted the update-templates branch November 26, 2024 14:27
# for free to join this conversation on GitHub. Already have an account? # to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants