User Preferences
Doctave supports dynamic content via user preferences. This means you can customize what content your readers will see based on preferences they've selected.
User preferences are useful when your product has different capabilities depending on, for example, the reader's plan.
You can for example:
- Hide specific content based on the reader's selected plan
- Show different instructions based on a region
- Tell users that a given feature isn't available for their account type
The user is able to select their preference from a dropdown in the navigation, and you can customize both the navigation and Markdown content based on their choice.
![Example of a user preference dropdown showing different plans the user can select from](https://doctave-assets-prod.s3.eu-central-1.amazonaws.com/assets/1/1/HtafKoqiu0MokHOpxrLAu8k4c3aqhEXkaHSw2M91Rhg/user-preferences-light.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA5SVLUIAJXFAOPOU6%2F20240902%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20240902T000000Z&X-Amz-Expires=604800&X-Amz-Signature=eff6e3cff826bdbbc5b19e87cfa2657761395a159738745d2339bf9a43c1630e&X-Amz-SignedHeaders=host&x-id=GetObject)
![Example of a user preference dropdown showing different plans the user can select from](https://doctave-assets-prod.s3.eu-central-1.amazonaws.com/assets/1/1/Pzw-IdbjQ7Yk-zGnbJebSHtKvDuCPT9HPwRTGTWKqOE/user-preferences-dark.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA5SVLUIAJXFAOPOU6%2F20240902%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20240902T000000Z&X-Amz-Expires=604800&X-Amz-Signature=b6b8053dde7da2a8d59e917f081c9121b1fe77e2260ebca4a59688eb966baa3f&X-Amz-SignedHeaders=host&x-id=GetObject)
Creating user preferences
To create a user preference, add a user preference object to your project file.
A user preference is a key-value pair that Doctave will use to customize the rendering of your documentation. See reference.
---
title: My Project
user_preferences:
plan:
label: My Plan
default: Starter
values:
- Starter
- Growth
- Enterprise
Adding a customized label for user preferences
You can choose to customize the label that's shown in the user preference selector.
---
title: My Project
user_preferences:
plan:
label: My Plan
default: starter
values:
- label: Starter Plan for Beginners
value: starter
- label: Growth Plan
value: growth
- label: Enterprise
value: enterprise
The label
is designed to be a prettier name for the preference that will be shown to users in the user preferences dropdowns. The value
field can be used by you in your documentation to show or hide content.
Customizing content
Once you have setup your user preferences, you can now customize your documentation depending on the user's currently selected preference.
Showing content based on user preferences
If you have defined a user preference called plan
, like above, you render some content conditionally with the Fragment
component.
<Fragment if={@user_preferences.plan == "Starter"}>
You are on the starter plan
</Fragment>
You use if={..}
on any Doctave component. Even your own custom ones!
Or, you can render the current value:
<Callout>
You are currently on the {@user_preferences.plan} plan
</Callout>
Customizing navigation based on user preferences
Sections in the navigation can be shown based on a condition, using the show_if
property.
- heading: API Reference
show_if:
user_preferences:
plan:
one_of:
- Growth
- Enterprise
In the above example, we're telling Doctave to only show the API Reference section if the user has selected as their plan either Growth or Enterprise.
Conditionals are based on matchers which you can use to determine when a section or link should be shown.
Equals
equals
is the simplest matcher. It checks that the given plan is an exact match.
show_if:
user_preferences:
plan:
equals: Enterprise
One Of
one_of
matcher expects as an argument
a list of values to match against.
show_if:
user_preferences:
plan:
one_of:
- Growth
- Enterprise