cabforum / build-guidelines-action

Action to build Pandoc-flavored Guidelines into their final form
0 stars 3 forks source link

Lint Markdown using `mdl` to enforce correct presentation #51

Open hablutzel1 opened 4 months ago

hablutzel1 commented 4 months ago

Currently there are some Markdown format issues in CA/B Forum documents like https://github.com/cabforum/servercert/blob/main/docs/BR.md.

For example the following Markdown excerpt from the TLS BRs:

### 4.9.7 CRL issuance frequency

CRLs must be available via a publicly-accessible HTTP URL (i.e., "published").

Within twenty-four (24) hours of issuing its first Certificate, the CA MUST generate and publish either:
- a full and complete CRL; OR
- partitioned (i.e., "sharded") CRLs that, when aggregated, represent the equivalent of a full and complete CRL.

CAs issuing Subscriber Certificates:  
1. MUST update and publish a new CRL at least every: 
     - seven (7) days if all Certificates include an Authority Information Access extension with an id-ad-ocsp accessMethod (“AIA OCSP pointer”); or
     - four (4) days in all other cases; 
2. MUST update and publish a new CRL within twenty-four (24) hours after recording a Certificate as revoked.

CAs issuing CA Certificates:  
1. MUST update and publish a new CRL at least every twelve (12) months;
2. MUST update and publish a new CRL within twenty-four (24) hours after recording a Certificate as revoked.

CAs MUST continue issuing CRLs until one of the following is true:
- all Subordinate CA Certificates containing the same Subject Public Key are expired or revoked; OR
- the corresponding Subordinate CA Private Key is destroyed.

Looks like this when converted into PDF:

brs_screenshot_before

Where you can see that lists are not rendered correctly.

Now, with the following corrected Markdown (see the extra blank lines around lists):

### 4.9.7 CRL issuance frequency

CRLs must be available via a publicly-accessible HTTP URL (i.e., "published").

Within twenty-four (24) hours of issuing its first Certificate, the CA MUST generate and publish either:

- a full and complete CRL; OR
- partitioned (i.e., "sharded") CRLs that, when aggregated, represent the equivalent of a full and complete CRL.

CAs issuing Subscriber Certificates:

1. MUST update and publish a new CRL at least every: 
     - seven (7) days if all Certificates include an Authority Information Access extension with an id-ad-ocsp accessMethod (“AIA OCSP pointer”); or
     - four (4) days in all other cases; 
2. MUST update and publish a new CRL within twenty-four (24) hours after recording a Certificate as revoked.

CAs issuing CA Certificates:

1. MUST update and publish a new CRL at least every twelve (12) months;
2. MUST update and publish a new CRL within twenty-four (24) hours after recording a Certificate as revoked.

CAs MUST continue issuing CRLs until one of the following is true:

- all Subordinate CA Certificates containing the same Subject Public Key are expired or revoked; OR
- the corresponding Subordinate CA Private Key is destroyed.

It would look like this:

brs_screenshot_after

This PR looks to enforce this correct Markdown style by introducing the usage of https://github.com/markdownlint/markdownlint/ during the workflow run.

Other Markdown linting rules (see https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md) could be enforced in the future or they could be passed as parameters to the Action.