Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/posit-dev/product-doc-theme
Shared theme for Posit product documentation
https://github.com/posit-dev/product-doc-theme
documentation
Last synced: about 1 month ago
JSON representation
Shared theme for Posit product documentation
- Host: GitHub
- URL: https://github.com/posit-dev/product-doc-theme
- Owner: posit-dev
- License: mit
- Created: 2024-01-19T14:59:57.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2024-04-22T12:43:44.000Z (5 months ago)
- Last Synced: 2024-04-22T13:54:42.391Z (5 months ago)
- Topics: documentation
- Language: SCSS
- Homepage: https://docs.posit.co/
- Size: 554 KB
- Stars: 3
- Watchers: 3
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- jimsghstars - posit-dev/product-doc-theme - Shared theme for Posit product documentation (SCSS)
README
# product-doc-theme
Shared theme for Posit product documentation
## Usage
First, install the extension:
```bash
quarto add posit-dev/[email protected]
```
Next, update your project type and format in `_quarto.yml`:
```yaml
project:
title: "Posit Documentation"
type: posit-docs
```
### Additional configuration entries
The following entries may be unique to each product. Please review the following and make manual updates to your project, as required.
#### Navbar
If you have `website.navbar.right` entries in your `_quarto.yml`,
merge the following with the existing entries:
```
website:
navbar:
right:
- icon: "list"
menu:
- text: "docs.posit.co"
href: "https://docs.posit.co"
- text: "Posit Support"
href: "https://support.posit.co/hc/en-us/"
```
#### Footer
Use the following `website.page-footer` in your `_quarto.yml`:
```
website:
page-footer:
left: |
Copyright © 2000-{{< env CURRENT_YEAR >}} Posit Software, PBC. All Rights Reserved.
center: |
Posit PRODUCT {{< env PRODUCT_VERSION >}}
right:
- icon: question-circle-fill
aria-label: 'Link to Posit Support'
href: "https://support.posit.co/hc/en-us"
- icon: lightbulb-fill
aria-label: 'Link to Posit Solutions'
href: "https://solutions.posit.co/"
- text: "
"
href: "https://docs.posit.co/"
- text: "
"
href: "https://posit.co/"
```
Make the following modifications:
- **Product name:** Replace the `PRODUCT` placeholder with the product name.
- **Product version:** Adapt the `PRODUCT_VERSION` variable for your product
based on how that information is made available. The example project gets
a default environment variable value from the
[`_environment`](https://quarto.org/docs/projects/environment.html) file.
You may need to dynamically define `PRODUCT_VERSION` before rendering your
documentation.
```bash
export PRODUCT_VERSION=$(cat version.txt)
```
- **Copyright:** Copyright dates are represented as a range from the year of
first product release until now. Adapt the `CURRENT_YEAR` variable for
your product and how that information is made available. The example
project gets a default environment variable value from the
[`_environment`](https://quarto.org/docs/projects/environment.html) file.
You may need to dynamically define `CURRENT_YEAR` before rendering your
documentation.
```bash
export CURRENT_YEAR=$(date "+%Y")
```
- **Images:** Copy the two images from the extension into your project and update the `src` paths.
For example, you may have a top-level `images` directory:
```bash
cp _extensions/posit-dev/posit-docs/assets/images/posit-guide-ltmd.svg images
cp _extensions/posit-dev/posit-docs/assets/images/posit-icon-fullcolor.svg images
```
These images are also available [from
GitHub](https://github.com/posit-dev/product-doc-theme/tree/main/_extensions/posit-docs/assets/images).
By copy/pasting and editing these entries into your project's yml, those entries will overwrite 1:1 entries in the `_extension.yml`.
## Development
If you are modifying this extension, use Quarto to preview your changes
against the sample project defined here.
```bash
quarto preview
```
### Release
To release a new version of this theme:
1. Make sure that the extension declares the target version and documents its
changes.
1. Update
[`README.md`](https://github.com/posit-dev/product-doc-theme/blob/main/README.md);
installation instructions reference the latest release version.
1. Update
[`_extensions/posit-docs/_extension.yml`](https://github.com/posit-dev/product-doc-theme/blob/main/_extensions/posit-docs/_extension.yml);
the extension declares its version.
1. Update
[`changelog.md`](https://github.com/posit-dev/product-doc-theme/blob/main/changelog.md);
make sure recent changes are announced.
Commit and merge both changes to `main`.
2. Tag the target commit and push the tag.
```bash
git tag -a v1.1.0 -m 'Release 1.1.0'
git push origin v1.1.0
```
3. Create a GitHub release from [that tag](https://github.com/posit-dev/product-doc-theme/tags).