-
-
Notifications
You must be signed in to change notification settings - Fork 600
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.
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
website/developer-docs: add a baby Style Guide #9900
Conversation
✅ Deploy Preview for authentik-storybook canceled.
|
✅ Deploy Preview for authentik-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #9900 +/- ##
========================================
Coverage 92.64% 92.64%
========================================
Files 710 713 +3
Lines 34744 34894 +150
========================================
+ Hits 32188 32327 +139
- Misses 2556 2567 +11
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
|
||
## Integration guidelines | ||
Whenever possible, use one of our [docs templates](./templates/index.md). This makes it a lot easier for you (no blank page frights!) and keeps the documentation consistent. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Shouldn't the singular of "docs" be used?
|
||
You can do local builds of the documentation to test your changes or review your new content, and to run the required `prettier` and linters before pushing your PR. | ||
|
||
The documentation site is situated in the `/website` folder of the repo. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Use website/ instead of /website because website/ indicates a relative path within the repository, while /website suggests an absolute path from the root directory.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ah, this is a topic I have often discussed/debated. :-) I do actually intend it to be shown as an absolute path from the root dir. If they start at root, I want them to know what dir to look for from there.
True there are relative paths after/within website
, but it's finding the top-level dir I want to focus on. Make sense?
authentik PR Installation instructions Instructions for docker-composeAdd the following block to your AUTHENTIK_IMAGE=ghcr.io/goauthentik/dev-server
AUTHENTIK_TAG=gh-ghcr.io/goauthentik/dev-server:gh-232e90de1e2a256930b45911802e5f9456838033
AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s For arm64, use these values: AUTHENTIK_IMAGE=ghcr.io/goauthentik/dev-server
AUTHENTIK_TAG=gh-ghcr.io/goauthentik/dev-server:gh-232e90de1e2a256930b45911802e5f9456838033-arm64
AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s Afterwards, run the upgrade commands from the latest release notes. Instructions for KubernetesAdd the following block to your authentik:
outposts:
container_image_base: ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s
image:
repository: ghcr.io/goauthentik/dev-server
tag: gh-ghcr.io/goauthentik/dev-server:gh-232e90de1e2a256930b45911802e5f9456838033 For arm64, use these values: authentik:
outposts:
container_image_base: ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s
image:
repository: ghcr.io/goauthentik/dev-server
tag: gh-ghcr.io/goauthentik/dev-server:gh-232e90de1e2a256930b45911802e5f9456838033-arm64 Afterwards, run the upgrade commands from the latest release notes. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just bein' nitpicky. :-)
@@ -28,48 +31,27 @@ The site is built using npm, below are some useful make commands: | |||
For real time viewing of changes, as you make them. | |||
|
|||
:::info | |||
Be sure to run the formatter before committing changes. | |||
Be sure to run a formatting command before committing changes. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"... the formatting command..." We have specific formatting commands:
make lint-fix
(for Django)make lint
(for Go and for other Python sources)cd web ; npm run prettier
(for the WebUI)cd website; npm run prettier
(for the web docs)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's possible I misunderstand the purpose of this document. For our product documentation (./website/
), we have the npm run prettier
command which will format your documents for you. (I'm surprised we don't run codespell or any other spell-check in there.). We have tools to enforce styling, and we should use more of them.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, about spell-check... I think we do run something, but whatever it is, is not as robust as what is in our final build pipeline! We will learn more soon, I hope. ;-)
@@ -121,6 +123,8 @@ This is documented in the [developer docs](./setup/frontend-dev-environment.md) | |||
|
|||
Contributions to the technical documentation are greatly appreciated. Open a PR if you have improvements to make or new content to add. If you have questions or suggestions about the documentation, open an Issue. No contribution is too small. | |||
|
|||
Please be sure to refer to our [Style Guide](../developer-docs/docs/style-guide.mdx) for the docs, and use a [template](./docs/templates/index.md) to make it easier for you. The style guidelines are also used for any Integrations documentation, and we have a template for Integrations as well, in our [Github repo](https://github.com/goauthentik/authentik) at `/website/integrations/_template/service.md`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You use the phrase [docs template]
in that link consistently up until this point. Why change?
|
||
Run this command before committing, to ensure consistent syntax, clean formatting, and verify links. Note that if the formatting command is not run, the build will fail with an error about linting. | ||
Run the appropriate formatting command for your set up before committing, to ensure consistent syntax, clean formatting, and verify links. Note that if the formatting command is not run, the build will fail with an error about linting. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
shouldn't "set up" be "setup"? What I saw online seems to point towards the second option
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
other than that, lgtm
* main: (2701 commits) website/developer-docs: add a baby Style Guide (#9900) website/integrations: gitlab: update certificate key pair location and specify sha (#9925) root: handle asgi exception (#10085) website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082) web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081) core: bump google-api-python-client from 2.132.0 to 2.133.0 (#10083) web: bump prettier from 3.3.1 to 3.3.2 in /tests/wdio (#10079) web: bump chromedriver from 125.0.3 to 126.0.0 in /tests/wdio (#10078) web: bump @sentry/browser from 8.8.0 to 8.9.1 in /web in the sentry group (#10080) web: bump braces from 3.0.2 to 3.0.3 in /web (#10077) website: bump braces from 3.0.2 to 3.0.3 in /website (#10076) web: bump braces from 3.0.2 to 3.0.3 in /tests/wdio (#10075) core: bump azure-identity from 1.16.0 to 1.16.1 (#10071) rbac: filters: fix missing attribute for unauthenticated requests (#10061) tests/e2e: docker-compose.yml: remove version element forgotten last time (#10067) providers/microsoft_entra: fix error when updating connection attributes (#10039) website/integrations: aws: fix about service link (#10062) translate: Updates for file locale/en/LC_MESSAGES/django.po in it (#10060) core: bump github.com/redis/go-redis/v9 from 9.5.2 to 9.5.3 (#10046) core: bump github.com/gorilla/websocket from 1.5.1 to 1.5.2 (#10047) ...
* main: (1301 commits) website/developer-docs: add a baby Style Guide (#9900) website/integrations: gitlab: update certificate key pair location and specify sha (#9925) root: handle asgi exception (#10085) website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082) web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081) core: bump google-api-python-client from 2.132.0 to 2.133.0 (#10083) web: bump prettier from 3.3.1 to 3.3.2 in /tests/wdio (#10079) web: bump chromedriver from 125.0.3 to 126.0.0 in /tests/wdio (#10078) web: bump @sentry/browser from 8.8.0 to 8.9.1 in /web in the sentry group (#10080) web: bump braces from 3.0.2 to 3.0.3 in /web (#10077) website: bump braces from 3.0.2 to 3.0.3 in /website (#10076) web: bump braces from 3.0.2 to 3.0.3 in /tests/wdio (#10075) core: bump azure-identity from 1.16.0 to 1.16.1 (#10071) rbac: filters: fix missing attribute for unauthenticated requests (#10061) tests/e2e: docker-compose.yml: remove version element forgotten last time (#10067) providers/microsoft_entra: fix error when updating connection attributes (#10039) website/integrations: aws: fix about service link (#10062) translate: Updates for file locale/en/LC_MESSAGES/django.po in it (#10060) core: bump github.com/redis/go-redis/v9 from 9.5.2 to 9.5.3 (#10046) core: bump github.com/gorilla/websocket from 1.5.1 to 1.5.2 (#10047) ...
* main: (320 commits) website/developer-docs: add a baby Style Guide (#9900) website/integrations: gitlab: update certificate key pair location and specify sha (#9925) root: handle asgi exception (#10085) website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082) web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081) core: bump google-api-python-client from 2.132.0 to 2.133.0 (#10083) web: bump prettier from 3.3.1 to 3.3.2 in /tests/wdio (#10079) web: bump chromedriver from 125.0.3 to 126.0.0 in /tests/wdio (#10078) web: bump @sentry/browser from 8.8.0 to 8.9.1 in /web in the sentry group (#10080) web: bump braces from 3.0.2 to 3.0.3 in /web (#10077) website: bump braces from 3.0.2 to 3.0.3 in /website (#10076) web: bump braces from 3.0.2 to 3.0.3 in /tests/wdio (#10075) core: bump azure-identity from 1.16.0 to 1.16.1 (#10071) rbac: filters: fix missing attribute for unauthenticated requests (#10061) tests/e2e: docker-compose.yml: remove version element forgotten last time (#10067) providers/microsoft_entra: fix error when updating connection attributes (#10039) website/integrations: aws: fix about service link (#10062) translate: Updates for file locale/en/LC_MESSAGES/django.po in it (#10060) core: bump github.com/redis/go-redis/v9 from 9.5.2 to 9.5.3 (#10046) core: bump github.com/gorilla/websocket from 1.5.1 to 1.5.2 (#10047) ...
…ore-dual-select-uses-2 * web/revision/more-dual-select-uses: (320 commits) website/developer-docs: add a baby Style Guide (#9900) website/integrations: gitlab: update certificate key pair location and specify sha (#9925) root: handle asgi exception (#10085) website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082) web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081) core: bump google-api-python-client from 2.132.0 to 2.133.0 (#10083) web: bump prettier from 3.3.1 to 3.3.2 in /tests/wdio (#10079) web: bump chromedriver from 125.0.3 to 126.0.0 in /tests/wdio (#10078) web: bump @sentry/browser from 8.8.0 to 8.9.1 in /web in the sentry group (#10080) web: bump braces from 3.0.2 to 3.0.3 in /web (#10077) website: bump braces from 3.0.2 to 3.0.3 in /website (#10076) web: bump braces from 3.0.2 to 3.0.3 in /tests/wdio (#10075) core: bump azure-identity from 1.16.0 to 1.16.1 (#10071) rbac: filters: fix missing attribute for unauthenticated requests (#10061) tests/e2e: docker-compose.yml: remove version element forgotten last time (#10067) providers/microsoft_entra: fix error when updating connection attributes (#10039) website/integrations: aws: fix about service link (#10062) translate: Updates for file locale/en/LC_MESSAGES/django.po in it (#10060) core: bump github.com/redis/go-redis/v9 from 9.5.2 to 9.5.3 (#10046) core: bump github.com/gorilla/websocket from 1.5.1 to 1.5.2 (#10047) ...
* main: (320 commits) website/developer-docs: add a baby Style Guide (#9900) website/integrations: gitlab: update certificate key pair location and specify sha (#9925) root: handle asgi exception (#10085) website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082) web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081) core: bump google-api-python-client from 2.132.0 to 2.133.0 (#10083) web: bump prettier from 3.3.1 to 3.3.2 in /tests/wdio (#10079) web: bump chromedriver from 125.0.3 to 126.0.0 in /tests/wdio (#10078) web: bump @sentry/browser from 8.8.0 to 8.9.1 in /web in the sentry group (#10080) web: bump braces from 3.0.2 to 3.0.3 in /web (#10077) website: bump braces from 3.0.2 to 3.0.3 in /website (#10076) web: bump braces from 3.0.2 to 3.0.3 in /tests/wdio (#10075) core: bump azure-identity from 1.16.0 to 1.16.1 (#10071) rbac: filters: fix missing attribute for unauthenticated requests (#10061) tests/e2e: docker-compose.yml: remove version element forgotten last time (#10067) providers/microsoft_entra: fix error when updating connection attributes (#10039) website/integrations: aws: fix about service link (#10062) translate: Updates for file locale/en/LC_MESSAGES/django.po in it (#10060) core: bump github.com/redis/go-redis/v9 from 9.5.2 to 9.5.3 (#10046) core: bump github.com/gorilla/websocket from 1.5.1 to 1.5.2 (#10047) ...
* main: (138 commits) website/developer-docs: add a baby Style Guide (#9900) website/integrations: gitlab: update certificate key pair location and specify sha (#9925) root: handle asgi exception (#10085) website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082) web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081) core: bump google-api-python-client from 2.132.0 to 2.133.0 (#10083) web: bump prettier from 3.3.1 to 3.3.2 in /tests/wdio (#10079) web: bump chromedriver from 125.0.3 to 126.0.0 in /tests/wdio (#10078) web: bump @sentry/browser from 8.8.0 to 8.9.1 in /web in the sentry group (#10080) web: bump braces from 3.0.2 to 3.0.3 in /web (#10077) website: bump braces from 3.0.2 to 3.0.3 in /website (#10076) web: bump braces from 3.0.2 to 3.0.3 in /tests/wdio (#10075) core: bump azure-identity from 1.16.0 to 1.16.1 (#10071) rbac: filters: fix missing attribute for unauthenticated requests (#10061) tests/e2e: docker-compose.yml: remove version element forgotten last time (#10067) providers/microsoft_entra: fix error when updating connection attributes (#10039) website/integrations: aws: fix about service link (#10062) translate: Updates for file locale/en/LC_MESSAGES/django.po in it (#10060) core: bump github.com/redis/go-redis/v9 from 9.5.2 to 9.5.3 (#10046) core: bump github.com/gorilla/websocket from 1.5.1 to 1.5.2 (#10047) ...
* main: website/developer-docs: add a baby Style Guide (#9900) website/integrations: gitlab: update certificate key pair location and specify sha (#9925) root: handle asgi exception (#10085) website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082) web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081) core: bump google-api-python-client from 2.132.0 to 2.133.0 (#10083) web: bump prettier from 3.3.1 to 3.3.2 in /tests/wdio (#10079) web: bump chromedriver from 125.0.3 to 126.0.0 in /tests/wdio (#10078) web: bump @sentry/browser from 8.8.0 to 8.9.1 in /web in the sentry group (#10080) web: bump braces from 3.0.2 to 3.0.3 in /web (#10077) website: bump braces from 3.0.2 to 3.0.3 in /website (#10076) web: bump braces from 3.0.2 to 3.0.3 in /tests/wdio (#10075) core: bump azure-identity from 1.16.0 to 1.16.1 (#10071)
* main: website/developer-docs: add a baby Style Guide (#9900) website/integrations: gitlab: update certificate key pair location and specify sha (#9925) root: handle asgi exception (#10085) website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082) web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081) core: bump google-api-python-client from 2.132.0 to 2.133.0 (#10083) web: bump prettier from 3.3.1 to 3.3.2 in /tests/wdio (#10079) web: bump chromedriver from 125.0.3 to 126.0.0 in /tests/wdio (#10078) web: bump @sentry/browser from 8.8.0 to 8.9.1 in /web in the sentry group (#10080) web: bump braces from 3.0.2 to 3.0.3 in /web (#10077) website: bump braces from 3.0.2 to 3.0.3 in /website (#10076) web: bump braces from 3.0.2 to 3.0.3 in /tests/wdio (#10075) core: bump azure-identity from 1.16.0 to 1.16.1 (#10071)
* dev: (335 commits) website/docs: release notes for 2024.6 (#9812) policies/reputation: save to database directly (#10059) providers/enterprise: import user/group data when manually linking objects (#10089) core, web: update translations (#10108) web: Add enterprise / FIPS notification to the AdminOverviewPage (#10090) core: bump github.com/getsentry/sentry-go from 0.28.0 to 0.28.1 (#10095) web: bump API Client version (#10107) admin: system api: do not show FIPS status if no valid license (#10091) root: add configuration option to enable fips (#10088) web: bump the sentry group across 1 directory with 2 updates (#10101) web: bump ts-pattern from 5.1.2 to 5.2.0 in /web (#10098) web: bump the storybook group across 1 directory with 7 updates (#10102) core: bump github.com/gorilla/websocket from 1.5.2 to 1.5.3 (#10103) core: bump pydantic from 2.7.3 to 2.7.4 (#10093) core: bump bandit from 1.7.8 to 1.7.9 (#10094) website/developer-docs: add a baby Style Guide (#9900) website/integrations: gitlab: update certificate key pair location and specify sha (#9925) root: handle asgi exception (#10085) website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082) web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081) ...
* main: (196 commits) website/docs: release notes for 2024.6 (#9812) policies/reputation: save to database directly (#10059) providers/enterprise: import user/group data when manually linking objects (#10089) core, web: update translations (#10108) web: Add enterprise / FIPS notification to the AdminOverviewPage (#10090) core: bump github.com/getsentry/sentry-go from 0.28.0 to 0.28.1 (#10095) web: bump API Client version (#10107) admin: system api: do not show FIPS status if no valid license (#10091) root: add configuration option to enable fips (#10088) web: bump the sentry group across 1 directory with 2 updates (#10101) web: bump ts-pattern from 5.1.2 to 5.2.0 in /web (#10098) web: bump the storybook group across 1 directory with 7 updates (#10102) core: bump github.com/gorilla/websocket from 1.5.2 to 1.5.3 (#10103) core: bump pydantic from 2.7.3 to 2.7.4 (#10093) core: bump bandit from 1.7.8 to 1.7.9 (#10094) website/developer-docs: add a baby Style Guide (#9900) website/integrations: gitlab: update certificate key pair location and specify sha (#9925) root: handle asgi exception (#10085) website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082) web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081) ...
This new Style Guide covers most of the basics that I often edit in contributions. We need to increase awareness of the Style Guide; in a subsequent PR I will add links to it in other places.
make website
)