You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat: Update repo READMEs and affected files (#783)
This commit removes the CHANGELOG file from the repository, as it was
not being used. The README and CONTRIBUTING files have been streamlined,
and now more accurately reflect the user flow when contributing.
Some GitHub templates have been updated to reflect these changes, and
also include relative links instead of axiomatic blobs, which will make
finding and updating links easier in the future.
Copy file name to clipboardExpand all lines: .github/pull_request_template.md
+3-3Lines changed: 3 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -26,10 +26,10 @@ Before merging a pull request, run through this checklist and mark each as compl
26
26
-[ ] I have rebased my branch onto main
27
27
-[ ] I have ensured my PR is targeting the main branch and pulling from my branch from my own fork
28
28
-[ ] I have ensured that the commit messages adhere to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary)
29
-
-[ ] I have ensured that documentation content adheres to [the style guide](https://github.com/nginx/documentation/blob/main/templates/style-guide.md)
29
+
-[ ] I have ensured that documentation content adheres to [the style guide](/documentation/style-guide.md)
30
30
-[ ] If the change involves potentially sensitive changes[^1], I have assessed the possible impact
31
31
-[ ] If applicable, I have added tests that prove my fix is effective or that my feature works
32
32
-[ ] I have ensured that existing tests pass after adding my changes
33
-
-[ ] If applicable, I have updated [`README.md`](https://github.com/nginx/documentation/blob/main/README.md) and [`CHANGELOG.md`](https://github.com/nginx/documentation/blob/main/CHANGELOG.md)
33
+
-[ ] If applicable, I have updated [`README.md`](/README.md)
34
34
35
-
[^1]: Potentially sensitive changes include anything involving code, personally identify information (PII), live URLs or significant amounts of new or revised documentation. Please refer to [our style guide](https://github.com/nginx/documentation/blob/main/templates/style-guide.md) for guidance about placeholder content.
35
+
[^1]: Potentially sensitive changes include anything involving code, personally identify information (PII), live URLs or significant amounts of new or revised documentation. Please refer to [our style guide](/documentation/style-guide.md) for guidance about placeholder content.
If you'd like to discuss something NGINX-related that doesn't involve documentation, you should go to the [NGINX Community Forum](https://community.nginx.org/).
36
34
37
35
## Submit a pull request
38
36
@@ -66,7 +64,6 @@ This repository does not include all of the source content for the NGINX documen
66
64
-[NGINX Open Source](https://github.com/nginx/nginx) - source for [NGINX changelog](https://nginx.org/en/CHANGES)
67
65
-[nginx.org](https://github.com/nginx/nginx.org) - source for https://nginx.org
68
66
-[NGINX Unit](https://github.com/nginx/unit) - source for https://unit.nginx.org
69
-
-[NGINX Ingress Controller](https://github.com/nginxinc/kubernetes-ingress/) - source for https://docs.nginx.com/nginx-ingress-controller
70
67
71
68
In those repositories, you can find documentation source code in the `docs` or `site` subdirectories.
<!-- These are the "repo [status badge](https://www.repostatus.org/)s" and the community support badges -->
8
-
9
7
# NGINX documentation
10
8
9
+
This repository contains the user documentation for NGINX's products, as well as the requirements to build and publish the documentation website.
10
+
11
+
Documentation is written in [Markdown](https://daringfireball.net/projects/markdown/basics), then transformed into HTML using the [Hugo](https://gohugo.io/) static site generator.
12
+
11
13
If you want to contribute to [F5 NGINX documentation](https://docs.nginx.com), you've come to the right place. We've organized a series of README-type files to help you get started:
12
14
13
15
-[Contributing](/CONTRIBUTING.md) describes how you can contribute to our documentation.
14
-
-[Contributing guidelines for experts](/CONTRIBUTING_DOCS.md) describes how you can contribute (and check your work) with Hugo, our static site generator
15
16
-[Code of Conduct](/CODE_OF_CONDUCT.md) describes expectations in the NGINX open source community.
16
17
-[License](/LICENSE) shows the license associated with work on this repository.
17
18
-[Security](/SECURITY.md) describes the procedures we would like you to follow if you find a security issue.
18
19
-[Support](/SUPPORT.md) lists how you can get support as a customer or a community member.
19
20
20
-
## Explanation
21
-
22
-
This repository contains user documentation for NGINX's products, as well as the requirements for linting, building, and publishing the documentation.
23
-
24
-
Our documentation is written in Markdown, specifically the [Goldmark](https://github.com/yuin/goldmark) Markdown parser.
25
-
We build our docs using [Hugo](https://gohugo.io) and host them in custom URLs on Azure.
21
+
You may also find the [documentation folder](/documentation/) for the repository interesting: it's where we store our process information.
Copy file name to clipboardExpand all lines: documentation/writing-hugo.md
+17-31Lines changed: 17 additions & 31 deletions
Original file line number
Diff line number
Diff line change
@@ -4,50 +4,35 @@ This page describes our guidelines on using [Hugo](https://gohugo.io/) to write
4
4
5
5
You will need [git](https://git-scm.com/) to interact with the repository and files: the content itself is written in Markdown.
6
6
7
-
Our workflow is to develop content locally, then submit a pull request once we've done our initial draft and editing passes.
7
+
Our workflow is to develop content locally, then [submit a pull request](/documentation/git-conventions.md) once we've done our initial draft and editing passes.
8
8
9
9
For guidance around how to write content, please check [the style guide](/documentation/style-guide.md).
10
10
11
11
## Setup
12
12
13
-
You will need to install Hugo _or_ Docker to build and preview docs in your local development environment.
13
+
You will need to install Hugo _or_ Docker to build or preview documentation in your local development environment.
14
14
15
-
Read the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information.
15
+
Read the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information: we are currently running [Hugo v0.147.8](https://github.com/gohugoio/hugo/releases/tag/v0.147.8) in production.
16
16
17
17
If you have [Docker](https://www.docker.com/get-started/) installed, there are fallbacks for all requirements in the [Makefile](Makefile), meaning you don't need to install them.
|_make watch_| Runs a local Hugo server, allowing for changes to be previewed in a browser. |
43
30
|_make drafts_| Runs a local Hugo server, rendering documents marked with `draft: true` in their metadata.|
44
-
|_make docs_| Builds the documentation in the local `public/` directory. |
45
-
|_make clean_| Removes the local `public` directory |
46
-
|_make hugo-get_| Updates the go module file with the latest version of the theme. |
47
-
|_make hugo-tidy_| Removes unnecessary dependencies from the go module file. |
48
-
|_make hugo-update_| Runs the hugo-get and hugo-tidy targets in sequence. |
49
-
|_make lint-markdown_| Runs [markdownlint](https://github.com/DavidAnson/markdownlint) on the content folder. |
50
-
|_make link-check_| Runs [markdown-link-check](https://github.com/tcort/markdown-link-check) on all Markdown files. |
31
+
|_make docs_| Builds the documentation in the local `public/` directory. |
32
+
|_make clean_| Removes the local `public` directory |
33
+
|_make hugo-get_| Updates the go module file with the latest version of the theme. |
34
+
|_make hugo-tidy_| Removes unnecessary dependencies from the go module file. |
35
+
|_make hugo-update_| Runs the hugo-get and hugo-tidy targets in sequence. |
51
36
52
37
## Add new documentation
53
38
@@ -67,9 +52,10 @@ This new page will be created with the default how-to archetype. To use a specif
67
52
68
53
Our archetypes [currently include](/archetypes/) the following:
69
54
70
-
-`default` (How-to instructions, general use)
71
-
-`concept`(An explanation of one implementation detail and some use cases)
72
-
-`tutorial` (An in-depth set of how-to instructions, referencing concepts)
55
+
-`default` - How-to instructions, general use
56
+
-`concept` - An explanation of one implementation detail and some use cases
57
+
-`tutorial` - An in-depth set of how-to instructions, referencing concepts
58
+
-`landing-page` - A special archetype for the landing page of a documentation set, with a unique layout
73
59
74
60
These archetypes are adapted from some existing [templates](/templates/): please [file an issue](https://github.com/nginx/documentation/issues/new?template=1-feature_request.md) if you would like a new archetype.
75
61
@@ -165,11 +151,11 @@ An example of this can be seen in [/content/ngf/get-started.md](https://github.c
165
151
Use the `img` shortcode to add images to documentation pages. It has the same parameters as the Hugo [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure).
- Do not include a forward slash at the beginning of the file path or it will [break the image](https://gohugo.io/functions/relurl/#input-begins-with-a-slash).
171
157
172
-
> **Important**: We have strict guidelines for using images. Review them in our [style guide](/templates/style-guide.md#guidelines-for-screenshots).
158
+
> **Important**: We have strict guidelines for using images. Review them in our [style guide](/documentation/style-guide.md#guidelines-for-screenshots).
0 commit comments