Skip to content

Commit e91433e

Browse files
volker-raschekvolker-raschek
committed
feat: introduction of markdownlinter and markdown-link-checker
The following patch introduces markdownlint and markdown-link-check and prepares bitnami's markdown parameter generator. [Markdownlinter](https://github.com/DavidAnson/markdownlint) is an open source application developed in NodeJS. It is available directly as a NodeJS application, or alternatively it can also be run as a GitHub Action. The GitHub Action can be obtained from the GitHub [Marketplace](https://github.com/marketplace/actions/markdownlint-cli2-action). In this specific patch, however, the application is installed natively via `package.json`. This has the advantage that developers are able to run the NodeJS application locally. Instead of having to remember `npm install` and `npm run`, as well as installing NodeJS locally, the patch adds a `Makefile`. The `Makefile` contains all the relevant npm commands as a dedicated target. Furthermore, the `Makefile` contains a wrapper to execute the commands in a container with NodeJS. This requires at least `docker` or `podman` to be installed. The default is `podman`. ```bash make readme/lint make container-run/readme/lint make container-run/readme/lint CONTAINER_RUNTIME=docker ``` The markdownlint application has a configuration file named `.markdownlint.yaml` and `.markdownignore`. I have adjusted the markdownlint configuration to the best of my knowledge in order to make as few changes as possible to the existing Markdown files. Probably the biggest change is the line break after 120 characters, which is introduced by the patch. As a second NodeJS application, the `package.json` contains the application `markdown-link-check`. This application checks all links in all Markdown files to see if they are accessible. This is to prevent links in documentation from becoming inaccessible. The source code of the application is hosted on [GitHub](https://github.com/tcort/markdown-link-check) and is available under the ISC license. The `Makefile` contains also dedicated targets to install and execute the NodeJS application: ```bash make readme/link make container-run/readme/link make container-run/readme/link CONTAINER_RUNTIME=docker ``` As the last NodeJS application, the patch prepares for the introduction of the readme-generator-for-helm application. This enables detailed documentation of attributes in `values.yaml` in the README. It is intended to actively help users understand the attributes in `values.yaml`. It does not introduce a `values.schema.json` file. The source code is also hosted on [GitHub](https://github.com/bitnami/readme-generator-for-helm) and is subject to the Apache 2.0 license. - Adjust the `values.yaml` so that the parameters are added to the `README.md`. - Introduction to [editorconfig](https://editorconfig.org/) - Adaptation of the directory structure to Helm [specifications](https://helm.sh/docs/topics/charts/). Signed-off-by: Markus Pesch <[email protected]>
1 parent 2191712 commit e91433e

File tree

10 files changed

+2981
-29
lines changed

10 files changed

+2981
-29
lines changed

‎.github/workflows/markdown-linters.yaml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Markdown linter
2+
3+
on:
4+
pull_request:
5+
paths: [ "**/*.md" ]
6+
types: [ "opened", "reopened", "synchronize" ]
7+
push:
8+
branches:
9+
- '**'
10+
paths: [ "**/*.md" ]
11+
tags-ignore:
12+
- '**'
13+
workflow_dispatch: {}
14+
15+
jobs:
16+
markdown-link-checker:
17+
container:
18+
image: docker.io/library/node:24.10.0-alpine
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Install tooling
22+
run: |
23+
apk update
24+
apk add git npm
25+
- uses: actions/[email protected]
26+
- name: Verify links in markdown files
27+
run: |
28+
npm install
29+
npm run readme:link
30+
31+
markdown-lint:
32+
container:
33+
image: docker.io/library/node:24.10.0-alpine
34+
runs-on: ubuntu-latest
35+
steps:
36+
- name: Install tooling
37+
run: |
38+
apk update
39+
apk add git
40+
- uses: actions/[email protected]
41+
- name: Lint markdown files
42+
run: |
43+
npm install
44+
npm run readme:lint

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,5 @@
55

66
# Helm resources
77
charts/*/charts
8+
9+
node_modules

‎.markdownlint.yaml‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# markdownlint YAML configuration
2+
# https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml
3+
4+
# Default state for all rules
5+
default: true
6+
7+
# Path to configuration file to extend
8+
extends: null
9+
10+
# MD003/heading-style/header-style - Heading style
11+
MD003:
12+
# Heading style
13+
style: "atx"
14+
15+
# MD004/ul-style - Unordered list style
16+
MD004:
17+
style: "dash"
18+
19+
# MD007/ul-indent - Unordered list indentation
20+
MD007:
21+
# Spaces for indent
22+
indent: 2
23+
# Whether to indent the first level of the list
24+
start_indented: false
25+
26+
# MD009/no-trailing-spaces - Trailing spaces
27+
MD009:
28+
# Spaces for line break
29+
br_spaces: 2
30+
# Allow spaces for empty lines in list items
31+
list_item_empty_lines: false
32+
# Include unnecessary breaks
33+
strict: false
34+
35+
# MD010/no-hard-tabs - Hard tabs
36+
MD010:
37+
# Include code blocks
38+
code_blocks: true
39+
40+
# MD012/no-multiple-blanks - Multiple consecutive blank lines
41+
MD012:
42+
# Consecutive blank lines
43+
maximum: 1
44+
45+
# MD013/line-length - Line length
46+
MD013:
47+
# Number of characters
48+
line_length: 120
49+
# Number of characters for headings
50+
heading_line_length: 120
51+
# Number of characters for code blocks
52+
code_block_line_length: 80
53+
# Include code blocks
54+
code_blocks: false
55+
# Include tables
56+
tables: false
57+
# Include headings
58+
headings: true
59+
# Strict length checking
60+
strict: false
61+
# Stern length checking
62+
stern: false
63+
64+
# MD022/blanks-around-headings/blanks-around-headers - Headings should be surrounded by blank lines
65+
MD022:
66+
# Blank lines above heading
67+
lines_above: 1
68+
# Blank lines below heading
69+
lines_below: 1
70+
71+
# MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content
72+
MD024:
73+
# Only check sibling headings
74+
siblings_only: true
75+
76+
# MD025/single-title/single-h1 - Multiple top-level headings in the same document
77+
MD025:
78+
# Heading level
79+
level: 1
80+
# RegExp for matching title in front matter
81+
front_matter_title: "^\\s*title\\s*[:=]"
82+
83+
# MD026/no-trailing-punctuation - Trailing punctuation in heading
84+
MD026:
85+
# Punctuation characters
86+
punctuation: ".,;:!。，；：！"
87+
88+
# MD029/ol-prefix - Ordered list item prefix
89+
MD029:
90+
# List style
91+
style: "one_or_ordered"
92+
93+
# MD030/list-marker-space - Spaces after list markers
94+
MD030:
95+
# Spaces for single-line unordered list items
96+
ul_single: 1
97+
# Spaces for single-line ordered list items
98+
ol_single: 1
99+
# Spaces for multi-line unordered list items
100+
ul_multi: 1
101+
# Spaces for multi-line ordered list items
102+
ol_multi: 1
103+
104+
# MD033/no-inline-html - Inline HTML
105+
MD033:
106+
# Allowed elements
107+
allowed_elements: []
108+
109+
# MD035/hr-style - Horizontal rule style
110+
MD035:
111+
# Horizontal rule style
112+
style: "---"
113+
114+
# MD036/no-emphasis-as-heading/no-emphasis-as-header - Emphasis used instead of a heading
115+
MD036:
116+
# Punctuation characters
117+
punctuation: ".,;:!?。，；：！？"
118+
119+
# MD041/first-line-heading/first-line-h1 - First line in a file should be a top-level heading
120+
MD041:
121+
# Heading level
122+
level: 1
123+
# RegExp for matching title in front matter
124+
front_matter_title: "^\\s*title\\s*[:=]"
125+
126+
# MD044/proper-names - Proper names should have the correct capitalization
127+
MD044:
128+
# List of proper names
129+
names:
130+
- Git
131+
- GitDevOps
132+
- GitHub
133+
- GitLab
134+
- GitOps
135+
- kube-prometheus-stack
136+
- Memcached
137+
- Nextcloud
138+
- Oracle
139+
- PostgreSQL
140+
- Prometheus
141+
- prometheus-exporter
142+
- SSL
143+
- TLS
144+
# Include code blocks
145+
code_blocks: false
146+
147+
# MD046/code-block-style - Code block style
148+
MD046:
149+
# Block style
150+
style: "fenced"
151+
152+
# MD048/code-fence-style - Code fence style
153+
MD048:
154+
# Code fence syle
155+
style: "backtick"

‎.markdownlintignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.github/
2+
Chart.lock
3+
charts/
4+
node_modules/

‎CODE_OF_CONDUCT.md‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,16 @@
1-
In the Nextcloud community, participants from all over the world come together to create Free Software for a free internet. This is made possible by the support, hard work and enthusiasm of thousands of people, including those who create and use Nextcloud software.
1+
# CODE OF CONDUCT
22

3-
Our code of conduct offers some guidance to ensure Nextcloud participants can cooperate effectively in a positive and inspiring atmosphere, and to explain how together we can strengthen and support each other.
3+
In the Nextcloud community, participants from all over the world come together to create Free Software for a free
4+
internet. This is made possible by the support, hard work and enthusiasm of thousands of people, including those who
5+
create and use Nextcloud software.
46

5-
The Code of Conduct is shared by all contributors and users who engage with the Nextcloud team and its community services. It presents a summary of the shared values and “common sense” thinking in our community.
7+
Our code of conduct offers some guidance to ensure Nextcloud participants can cooperate effectively in a positive and
8+
inspiring atmosphere, and to explain how together we can strengthen and support each other.
69

7-
You can find our full code of conduct on our website: https://nextcloud.com/contribute/code-of-conduct/
10+
The Code of Conduct is shared by all contributors and users who engage with the Nextcloud team and its community
11+
services. It presents a summary of the shared values and “common sense” thinking in our community.
812

9-
Please, keep our CoC in mind when you contribute! That way, everyone can be a part of our community in a productive, positive, creative and fun way.
13+
You can find our full code of conduct on our website: <https://nextcloud.com/contribute/code-of-conduct/>
14+
15+
Please, keep our CoC in mind when you contribute! That way, everyone can be a part of our community in a productive,
16+
positive, creative and fun way.

‎CONTRIBUTING.md‎

Lines changed: 23 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,35 @@
1-
# Welcome
1+
# CONTRIBUTING
22

3-
Thanks for considering a contribution to this Nextcloud repository run by the community! Please make sure you review the [Code of Conduct](./CODE_OF_CONDUCT.md) before proceeding, and keep in mind that this repository is run by volunteers.
3+
Thanks for considering a contribution to this Nextcloud repository run by the community! Please make sure you review the
4+
[Code of Conduct](./CODE_OF_CONDUCT.md) before proceeding, and keep in mind that this repository is run by volunteers.
45

5-
# Pull Requests
6+
## Pull Requests
67

7-
Before submitting a feature or fix PR, please make sure your changes are targetted to one feature or fix, and all your commits are signed off. (Learn more the DCO [here](https://probot.github.io/apps/dco))
8+
Before submitting a feature or fix PR, please make sure your changes are targeted to one feature or fix, and all your
9+
commits are signed off. (More about Developer Certificate of Origin is [documented](https://probot.github.io/apps/dco)
10+
online.
811

912
If you're making a change to the chart templates or `values.yaml`, please also do the following:
1013

1114
1. Ensure the chart is linted using [`helm lint`](https://helm.sh/docs/helm/helm_lint/)
1215
2. Test rendering the helm templates from the chart root dir (`charts/nextcloud`) using `helm template .`
13-
- If you're making a change to a non-default value, please also test that value change locally. You can pass in a custom values file to `helm template` with `--values mycustomvalues.yaml`
14-
3. Test installing the chart. A great tool for this is [`ct`](https://github.com/helm/chart-testing/tree/main) using [`ct install`](https://github.com/helm/chart-testing/blob/main/doc/ct_install.md) on a test cluster like [kind](https://kind.sigs.k8s.io/)
15-
4. Make sure new or changed values are updated in the [values.yaml](./charts/nextcloud/values.yaml) and the [README.md](./charts/nextcloud/README.md)
16-
5. Bump the `version` in the [Chart.yaml](./charts/nextcloud/Chart.yaml) according to [Semantic Versioning](https://semver.org) which uses the format `major.minor.patch`.
17-
18-
Then, please make sure you follow the [pull request template](.github/pull_request_template.md), so we can more quickly review. In order to move your PR forward faster (for instance, bumping the helm chart version for you), please also check the "Allow edits and access to secrets by maintainers" box next to the "Create pull request" button:
16+
- If you're making a change to a non-default value, please also test that value change locally. You can pass in a
17+
custom values file to `helm template` with `--values mycustomvalues.yaml`
18+
3. Test installing the chart. A great tool for this is [`ct`](https://github.com/helm/chart-testing/tree/main) using
19+
[`ct install`](https://github.com/helm/chart-testing/blob/main/doc/ct_install.md) on a test cluster like
20+
[kind](https://kind.sigs.k8s.io/)
21+
4. Make sure new or changed values are updated in the [values.yaml](./charts/nextcloud/values.yaml) and the
22+
[README.md](./charts/nextcloud/README.md)
23+
5. Bump the `version` in the [Chart.yaml](./charts/nextcloud/Chart.yaml) according to [Semantic
24+
Versioning](https://semver.org) which uses the format `major.minor.patch`.
25+
26+
Then, please make sure you follow the [pull request template](.github/pull_request_template.md), so we can more quickly
27+
review. In order to move your PR forward faster (for instance, bumping the helm chart version for you), please also
28+
check the "Allow edits and access to secrets by maintainers" box next to the "Create pull request" button:
1929

2030
![screenshot of the allow edits by maintainers check box to the left of the Create pull request button on GitHub](https://github.com/nextcloud/helm/assets/2389292/3a8044a9-583d-496a-b3d2-4dd699c56ed4)
2131

32+
## Issues
2233

23-
# Issues
24-
25-
Please make sure you follow one of the [issue templates](.github/ISSUE_TEMPLATE) so we can better help troubleshoot with you.
34+
Please make sure you follow one of the [issue templates](.github/ISSUE_TEMPLATE) so we can better help troubleshoot with
35+
you.

‎Makefile‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# CONTAINER_RUNTIME
2+
CONTAINER_RUNTIME?=$(shell which podman)
3+
4+
# NODE_IMAGE
5+
NODE_IMAGE_REGISTRY_HOST?=docker.io
6+
NODE_IMAGE_REPOSITORY?=library/node
7+
NODE_IMAGE_VERSION?=24.10.0-alpine # renovate: datasource=docker registryUrl=https://docker.io depName=docker.io/library/node packageName=library/node
8+
NODE_IMAGE_FULLY_QUALIFIED=${NODE_IMAGE_REGISTRY_HOST}/${NODE_IMAGE_REPOSITORY}:${NODE_IMAGE_VERSION}
9+
10+
# MISSING DOT
11+
# ==============================================================================
12+
missing-dot:
13+
grep --perl-regexp '## @(param|skip).*[^.]$$' values.yaml
14+
15+
# README
16+
# ==============================================================================
17+
readme: readme/link readme/lint readme/parameters
18+
19+
readme/link:
20+
npm install && npm run readme:link
21+
22+
readme/lint:
23+
npm install && npm run readme:lint
24+
25+
readme/parameters:
26+
npm install && npm run readme:parameters
27+
28+
# CONTAINER RUN - README
29+
# ==============================================================================
30+
PHONY+=container-run/readme
31+
container-run/readme: container-run/readme/link container-run/readme/lint container-run/readme/parameters
32+
33+
container-run/readme/link:
34+
${CONTAINER_RUNTIME} run \
35+
--rm \
36+
--volume $(shell pwd):$(shell pwd) \
37+
--workdir $(shell pwd) \
38+
${NODE_IMAGE_FULLY_QUALIFIED} \
39+
npm install && npm run readme:link
40+
41+
container-run/readme/lint:
42+
${CONTAINER_RUNTIME} run \
43+
--rm \
44+
--volume $(shell pwd):$(shell pwd) \
45+
--workdir $(shell pwd) \
46+
${NODE_IMAGE_FULLY_QUALIFIED} \
47+
npm install && npm run readme:lint
48+
49+
container-run/readme/parameters:
50+
${CONTAINER_RUNTIME} run \
51+
--rm \
52+
--volume $(shell pwd):$(shell pwd) \
53+
--workdir $(shell pwd) \
54+
${NODE_IMAGE_FULLY_QUALIFIED} \
55+
npm install && npm run readme:parameters
56+
57+
# PHONY
58+
# ==============================================================================
59+
# Declare the contents of the PHONY variable as phony. We keep that information
60+
# in a variable so we can use it in if_changed.
61+
.PHONY: ${PHONY}

0 commit comments

Comments
 (0)