Repository files navigation

Welcome to the documentation of allDuende Software products and open-source tools!

You will need Node 22+ installed on your operating system and available in the PATH.

• Runnpm install to restore all dependencies.
• Usenpm run dev to run the documentation site locally.

Alternatively in VS Code, GitHub Codespaces, or WebStorm, you can use the devcontainer to get a development environment set up.

This project uses Astro + Starlight. You'll see the following folders and files:

.├── public/├── src/│   ├── assets/│   ├── content/│   │   ├── docs/│   └── content.config.ts├── astro.config.mjs├── package.json└── tsconfig.json

Starlight looks for.md or.mdx files in thesrc/content/docs/ directory. Each file is exposed as a route based on its file name.

Images can be added tosrc/assets/ and embedded in Markdown with a relative link.

Static assets, like favicons, can be placed in thepublic/ directory.

Content can be authored in Markdown, in a.md or.mdx file. The Starlight documentation has some guidance on Markdown syntax, components, and more:

• Authoring Content in Markdown
• Using Components (only in.mdx)

Use a spell checker likeGrazie orGrammarly to check your content for spelling and grammar errors.WebStorm has Grazie as a built-in spell checker and grammar checker, and supports a good default writing style.

• Use the active voice. For example, use "Enable" instead of "Enabled" or "Enabling".
• Use the second person ("you" not "I" or "we"). "You" is the reader of the documentation. "We" is Duende Software.
• Use sentence case in text. Titles use Title Case.
• Use the Oxford comma.
• Avoid words like "very", "simple", "easy", ...
• "As well as" can be written as "and".
• Avoid flowery language.
• When using acronyms, use the full form with parentheses the first time you use it. For example, use "Multi-Factor Authentication (MFA)" instead of "MFA".

• Always prefer linking internally over linking externally. For example, when you talk about data protection, prefer an internal link over a link to external sites.
• When linking to external content, consider writing one or two sentences about the context and what the reader will learn on the linked page.
• When linking other pages, use a path that starts at the content root, like/identityserver/troubleshooting/index.md. Use the.md(x) file extension - Starlight will update the link to the correct format on build.
• When linking to external resources, use the full URL using HTTPS.
• You can link to header anchors using the# symbol, for example[multiple authentication methods](/identityserver/ui/federation.md#multiple-authentication-methods-for-users).
• Link relevant text. Preferlearn more about [improving the sign-in experience] overclick [here] to learn more.
• Runnpm run linkchecker to validate all links (note this will ignore links to GitHub because of rate limits in place).
• When a markdown link is long (75+ characters) or a link is repeated multiple times on a page, prefer moving the link to the bottom of the file and using markdown anchor syntax[test.cs][repo-test-file]

• Use* for lists. Do not use-.
• Use[link title](https://example.com) for links, avoid reference-style links unless you need to repeat the same link multiple times.
• For internal links, always include the extension (e.g..md or.mdx)
• Prefercsharp overcs to set the language for C# code blocks.

• Use triple backticks to enclose code blocks.
• Use a language identifier to specify the language (e.g.csharp,bash,json,html,javascript,typescript,css,json)
• Add a title to the code block. You can do this adding the title as a comment in the first line of the code block (e.g.// Program.cs).
• Useexpressive code features.
• Readers should not need to scroll horizontally to read a code example. Simplify and condense the code as much as possible.
• If writing C#, use the latest syntax — including top-level statements, collection expressions, ...
• Make sure examples are runnable and complete. The goal is "Copy-paste from docs". Include namespaces, a result, and other prerequisites that are not obvious to someone new to the code.
• Inline comments can be used to explain essential parts of the code. Expressive code can highlight line numbers, show diffs, and more.
• Mention NuGet packages as abash code block showing how to install it (dotnet add package ...). Link to the NuGet Gallery.
• When referencing a property, field, class, or other symbol in text, use thetest format instead oftest.
• Values should also be back-ticked, especially HTTP Status codes like404 or401.
• Make sure code blocks start at the very first character space and don't have excessive starting padding.

• Always have atitle property to set the page title.

• Always have adescription property to set the page description. This is a summary of the page's core content.

• Always have adate property to set the creation/significant update date for a page. Use theYYYY-MM-DD format.

• Add thesidebar property and must include thelabel andorder. Thelabel is used in the menu, and should typically be shorter than the more descriptivetitle. For example:

  title:"Using IdentityServer As A Federation Gateway"sidebar:label:"Federation"order:1

All commands are run from the root of the project, from a terminal:

There are two ways to restructure content:

• Internal (move content around in the current structure)
• External (move content outside the current structure)

When doing internal restructuring, move the page to its new location and then update its frontmatterto include the old location:

---title:Page titleredirect_from:  -/old-path-to/content---Page content goes here

This will generate the page at the new location, and put a redirect to it at the old location.

When moving a page outside the structure, or you need a redirect to another location altogether,edit theastro.config.mjs file and append a key/vaklue pair to theredirects property:

redirects: {"/identityserver/product-page":"https://duendesoftware.com/products/identityserver",},

This will remove the old page from the navigation structure, but keeps the URL aroundwith a redirect to the new location.

For all licensing information, refer to the relevant license files:

• LICENSE - License for the documentation site content.
• LICENSE-CODE - License for the code samples.

The Astro documentation engine is licensed under theMIT license.