From a9110a709ccbbd2e8f3713832a4ea84f454823f5 Mon Sep 17 00:00:00 2001 From: Aaron Ritter Date: Sat, 25 Apr 2026 22:24:38 +0200 Subject: [PATCH 01/12] Add glossary page example for glossary system --- src/pages/glossary.astro | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 src/pages/glossary.astro diff --git a/src/pages/glossary.astro b/src/pages/glossary.astro new file mode 100644 index 0000000000..6f148ff7db --- /dev/null +++ b/src/pages/glossary.astro @@ -0,0 +1,19 @@ +--- +import glossary from '../data/glossary.json'; +--- + +

Glossary

+ From c9e1dcbd1acb7e4065451fc2ef1babad1c66fbea Mon Sep 17 00:00:00 2001 From: Aaron Ritter Date: Sat, 25 Apr 2026 22:25:42 +0200 Subject: [PATCH 02/12] =?UTF-8?q?docs:=20add=20guideline=20for=20glossary?= =?UTF-8?q?=20system=E2=80=94including=20how=20to=20add,=20link,=20and=20r?= =?UTF-8?q?eference=20glossary=20terms=20using=20the=20GlossaryTerm=20comp?= =?UTF-8?q?onent?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 380 ++---------------------------------------------- 1 file changed, 15 insertions(+), 365 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 09b2e110ad..5d9470977d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,13 +2,13 @@ > NOTE: To build the docs site, see the [docs README](/astro/README.md). -Here are some guidelines to follow when writing documentation (everything under [docs](astro/src/content/docs)), articles (everything under [articles](astro/src/content/articles)), and blogs [blog](astro/src/content/blog): +Here are some guidelines to follow when writing documentation (everything under [docs](astro/src/content/docs)), articles (everything under [articles](astro/src/content/articles)), and blogs [blog](/astro/src/content/blog): - Capitalize all domain objects, especially when working the object's API in which it is created and updated in FusionAuth. For example, see the API Key APIs description for `apiKeyId`, where API Key is capitalized: `The unique Id of the API Key to create. If not specified a secure random UUID will be generated.` - If referring to something that exists as a domain object in FusionAuth, but you are not explicitly referring to an object being created/updated in FusionAuth, use lowercase. Here are some examples: `To allow users to log into and use your application, you’ll need to create an Application in FusionAuth.` -- From the Link API, note the difference between a FusionAuth User and a 3rd party user: `This API is used to create a link between a FusionAuth User and a user in a 3rd party identity provider. This API may be useful when you already know the unique Id of a user in a 3rd party identity provider and the corresponding FusionAuth User.` +- From the Link API, note the difference between a FusionAuth User and a 3rd party user: `This API is used to create a link between a FusionAuth User and a user in a 3rd party identity provider. This allows FusionAuth to reconcile logins across both systems.` - Do not manually wrap long lines. Use the soft wrap in your editor to view while editing. - Use `Id` instead of `ID` or `id` when describing a unique identifier - Use `admin UI` instead of `Admin UI` when writing about the admin user interface. @@ -21,7 +21,7 @@ Here are some guidelines to follow when writing documentation (everything under - Use "a" or "an" before an initialism or acronym based on how the first letter sounds when spoken - for example, "an SSO" because "S" sounds like "ess" (vowel sound), but "a VPN" because "V" sounds like "vee" (consonant sound). - References to `http://127.0.0.1` should be updated to `http://localhost`. Remove hyperlinks to `localhost`. - Always provide an alt text for images. It should always be a full sentence describing the content of the image. -- In general, put screenshot images after the text describing the image. That is "This functionality....\n\n". However, when describing fields for screens, as in the core concepts section, put the screenshot first. +- In general, put screenshot images after the text describing the image. That is "This functionality....\n\n". However, when describing fields for screens, as in the create tenant screen, put screenshots above the list of fields. Images should never precede their reference in text. - If possible use an SVG for images. Otherwise, a PNG that has been properly minified is acceptable. - Never use the term GUID, it's always UUID. If you mention any, display them in `8-4-4-4-12` format: `631ecd9d-8d40-4c13-8277-80cedb8236e3` - When introducing a code snippet, don't use a : (colon). Instead, just use verbiage before it. "The code to exchange the token is similar to below." @@ -31,369 +31,19 @@ Here are some guidelines to follow when writing documentation (everything under - All image captions should be one or more complete sentences. - Use the oxford comma. Apples, bananas, and oranges are my favorite fruits. - Single spaces should be used instead of double spaces after a period. -- Headers should have the first letter of every word capitalized: `This Is The Header Text`. This is true for all headers (h1, h2, h3, h4). This is also known as [Start Case](https://en.wikipedia.org/wiki/Letter_case). -- When writing, you have access to Asides. Here's an [example blog post using an Aside](https://github.com/FusionAuth/fusionauth-site/blob/main/astro/src/content/blog/log4j-fusionauth.mdx). You can assign the following values to the type: `tip` for tips. `note` for things for the user to be aware of. `important` for things the user should pay attention to. `warn` for dangerous actions like deleting a tenant. -- For links, don't use the absolute URL for the FusionAuth website (https://fusionauth.io), only relative URLs. This allows us to deploy to our local and staging environments and not get sent over to prod. +- Headers should have the first letter of every word capitalized: `This Is The Header Text`. This is true for all headers (h1, h2, h3, h4). This is also known as [Start Case](https://en.wikipedia.org/wiki/Letter_case#Stylistic_or_specialised_usage). +- When writing, you have access to Asides. Here's an [example blog post using an Aside](https://github.com/FusionAuth/fusionauth-site/blob/main/astro/src/content/blog/log4j-fusionauth.mdx). You can use `