Include instructions / code to support hugo builds #15
Conversation
mjang
force-pushed
the
doc-build-instructions
branch
3 times, most recently
from
a48a929 to
404fc83
Compare
mjang
force-pushed
the
doc-build-instructions
branch
2 times, most recently
from
721ddfe to
43a0372
Compare
| - [ ] I have read the [contributing guidelines](/CONTRIBUTING.md). | ||
| - [ ] I have signed the [F5 Contributor License Agreement (CLA)](https://github.com/f5/.github/blob/main/CLA/cla-markdown.md). | ||
| - [ ] 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`](/README.md) and [`CHANGELOG.md`](/CHANGELOG.md)). | ||
| - [ ] I have rebased my branch onto main | ||
| - [ ] I will ensure my PR is targeting the main branch and pulling from my branch from my own fork | ||
| - [ ] If the change involves: |
There was a problem hiding this comment.
IA thing: I'd consider re-ordering these based on how frequently someone will come in contact with them. I often check the box for contributing in PRs despite being well aware of the policy: the F5 CLA is only required on the user's first interaction with a repo, and the bot enforces it as a requirement.
There was a problem hiding this comment.
@ADubhlaoich I hear you. I've tried to "respect" the existing checklist order from various NGINX repos. I'm personally good with the order, since contributing guidelines and the CLA are prerequisites.
| - Release notes | ||
| - Tutorial | ||
|
|
||
| ## How to format docs |
There was a problem hiding this comment.
| ## How to format docs | |
| ## How to format documentation |
| ### How to format internal links | ||
|
|
||
| Internal links should use Hugo [ref and relref shortcodes](https://gohugo.io/content-management/cross-references/). | ||
|
|
||
| - Although file extensions are optional for Hugo, we include them as best practice for page anchors. | ||
| - Relative paths are preferred, but just the filename is permissible. | ||
| - Paths without a leading forward slash (`/`) are first resolved relative to the current page, then the remainder of the website. | ||
|
|
||
| Here are two examples: | ||
|
|
||
| ```md | ||
| To install <software>, refer to the [installation instructions]({{< ref "install.md" >}}). | ||
| To install <integation>, refer to the [integration instructions]({{< relref "/integration/thing.md#section" >}}). | ||
| ``` | ||
|
|
There was a problem hiding this comment.
No feedback, really: I've taken to just using ref since the way we use relref is redundant.
Having the full, explicit path is much clearer, especially when you're making IA changes (Which I seem to do often).
I'm not sure if this would be worth proposing as a convention going forward.
There was a problem hiding this comment.
I personally agree, but think we should come to a consensus as a documentation group before making that kind of change.
| > **Important**: We have strict guidelines regarding the use of images in our documentation. Make sure that you keep the number of images to a minimum and that they are relevant to the content. Review the guidelines in our [style guide](/templates/style-guide.md#guidelines-for-screenshots). | ||
| ### How to use Hugo shortcodes |
There was a problem hiding this comment.
Might be nice to include our new ghcode shortcode here.
Every change to this file has to be reflected in all of the other counterparts, but I am inclined to be lazy about updating the others on the basis that this will eventually be the sole documentation repo for NGINX projects.
There was a problem hiding this comment.
Looks cool! I don't see ghcode at least in our current repositories.
- Include go files to support F5/NGINX Hugo theme - Add files which support `make` for different build types - Set up a compatible code request template - Update .gitignore, go files - Include min 2 approvals for potential security issues - Add detailed "which repo" instructions to F5-NGINX-team-notes
mjang
force-pushed
the
doc-build-instructions
branch
from
114a4ad to
0d9f663
Compare
|
Notes:
I'm therefore proceeding with merge. |
2 participants
makefor different build typesProposed changes
Detailed info on how users can build their own docs, based on the standard NGINX Open Source CONTRIBUTING.md. file. However, I've done this in CONTRIBUTING_DOCS.md, as our template for new open source repos has its own CONTRIBUTING.md file.
I've also included files needed to build docs locally, such as Makefile, go.*, etc. In my tests, users can now run the
makecommands described in CONTRIBUTING_DOCS.md.This is sort of a meshing of "README"-type files our current open docs repos and the template repository, including the .github/pull_request_template.md file.
Checklist
Before creating a PR, run through this checklist and mark each as complete:
README.mdandCHANGELOG.md).