8000 Add documentation style guide and tool configs by danbarr · Pull Request #5320 · mindersec/minder · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

Add documentation style guide and tool configs #5320

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jan 18, 2025
Merged

Add documentation style guide and tool configs #5320

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
383802b
Add eslint, markdownlint, and prettier configs
danbarr Jan 10, 2025
ad0c86d
Update node engine version
danbarr Jan 10, 2025
4f26cbc
Fix generated CLI docs path
danbarr Jan 10, 2025
7db57b7
Add style guide and update README
danbarr Jan 17, 2025
36cb1b6
Bump tools and add Dependabot group for eslint
danbarr Jan 17, 2025
4253214
Add license header
danbarr Jan 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .gitattributes
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
# linguist-generated causes generated files to not be expanded during code review.

/database/mock/*.go linguist-generated=true
/docs/docs/cli/*.md linguist-generated=true
/docs/docs/ref/cli/*.md linguist-generated=true
/docs/docs/ref/schema.md linguist-generated=true
/docs/docs/ref/proto.md linguist-generated=true
/pkg/api/openapi/** linguist-generated=true
Expand Down
3 changes: 3 additions & 0 deletions .github/dependabot.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,9 @@ updates:
docusaurus:
patterns:
- "*docusaurus*"
eslint:
patterns:
- "*eslint*"
ignore:
# facebook/docusaurus#4029 suggests MDX v2 will only be in the v3 release.
# facebook/docusaurus#9053 has some more details on the migration.
Expand Down
11 changes: 11 additions & 0 deletions docs/.markdownlint-cli2.jsonc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"gitignore": true,
"globs": ["**/*.md"],
"ignores": [
"node_modules/",
".docusaurus",
"build/",
"docs/ref/cli/",
"docs/ref/proto.md",
],
}
37 changes: 37 additions & 0 deletions docs/.markdownlint.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
{
"code-block-style": {
"style": "fenced"
},
"code-fence-style": {
"style": "backtick"
},
"emphasis-style": {
"style": "underscore"
},
"heading-style": {
"style": "atx"
},
"hr-style": {
"style": "---"
},
"line-length": {
"code_blocks": false,
"line_length": 80,
"tables": false
},
"no-bare-urls": false,
"no-duplicate-heading": false,
"proper-names": {
"code_blocks": false,
"names": ["GitHub", "GitLab", "Bitbucket"]
},
"strong-style": {
"style": "asterisk"
},
"table-pipe-style": {
"style": "leading_and_trailing"
},
"ul-style": {
"style": "dash"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I always use *, but this dog can learn new tricks!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I used to also; the rationale I drew this from was that it's easier to read when you do things like this:

* **A bold bullet**

vs.

- **A bold b
8000
ullet**

But frankly, this is a nit - if * are more comfortable/natural I'm not opposed to changing this - consistency is more important than which character.

Markdownlint also support a sublist style which uses different symbols as you nest:

* Item 1
  + Item 2
    - Item 3
  + Item 4
* Item 4
  + Item 5

}
}
7 changes: 7 additions & 0 deletions docs/.prettierignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
node_modules/
.docusaurus/
build/

# Auto-generated files
docs/ref/cli/*.md
docs/ref/proto.md
9 changes: 9 additions & 0 deletions docs/.prettierrc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"jsxSingleQuote": true,
"printWidth": 80,
"proseWrap": "always",
"singleQuote": true,
"tabWidth": 2,
"trailingComma": "es5",
"useTabs": false
}
59 changes: 50 additions & 9 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,66 @@
# Docs for Minder
# Minder documentation

This directory contains the user documentation for Minder, hosted at
<https://mindersec.github.io>.

The docs are built with [Docusaurus](<[https://](https://docusaurus.io/)>), an
open source static website generator optimized for documentation use cases.

## Contributing to docs

We welcome community contributions to the Minder documentation - if you find
something missing, wrong, or unclear, please let us know via an issue or open a
PR!

Please review the [style guide](./STYLE-GUIDE.md) for help with voice, tone, and
formatting.

## Building the docs locally

Start from the top level directory of the repository.
Start from the top level directory of the `minder` repository and generate the
CLI docs:

Generate the CLI docs
```
```bash
make cli-docs
```

Build the docs
```
cd docs
```
Run a preview server:

```bash
npm run start
```

Your browser should automatically open to <http://localhost:3000>

Build the docs:

```bash
cd docs
npm run build
```

Serve the docs
```

```bash
npm run serve -- --port 3001
```

Visit http://localhost:3001/ to view the docs.

## Formatting

Before you submit a PR, please check for formatting and linting issues:

```bash
npm run prettier
npm run markdownlint
npm run eslint
```

To automatically fix issues:

```bash
npm run prettier:fix
npm run markdownlint:fix
npm run eslint:fix
```
Loading
Loading
0