Skip to content

Single-sourcing documentation & examples created #259

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.

Sign up for GitHub

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

Merged
validbeck merged 3 commits into from
Aug 1, 2024
Merged

Single-sourcing documentation & examples created #259

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4d79181
Example pages created
validbeck Jul 31, 2024
bf5f1b0
Removed example pages from navigation
validbeck Jul 31, 2024
4f45561
Why did it not delete it from the site/internal folder the 1st time
validbeck Aug 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions site-unused/testing/single-sourcing/_source-file.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
## Create the source file

1. Create a new file for the single-source information. In this example, we’ll call it: `_source-file.qmd`

1. Copy and paste the instructions from the original file you’re extracting the information from

1. Replace all the numbered headings with `1.` and markdown will take care of the rest

1. Clean up any footnotes (by replacing them with inline links) etc.

## Include the source in the destination file

1. Return to your original file, and replace the extracted information with the new source file: `{{< include _source-file.qmd >}}`

1. Re-render the preview for the original file, to make sure that it looks and works as expected; make any necessary tweaks
19 changes: 19 additions & 0 deletions site-unused/testing/single-sourcing/destination-file.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
title: "Single-sourcing instructions"
subtitle: "Destination file"
search: false
---

## Introduction & conventions

::: {.callout}
Single-sourcing information in the docs site makes use of [Quarto’s Includes functionality](https://quarto.org/docs/authoring/includes.html).
:::

- Single-sourced information should live in the same directory as the original file it was extracted from.
- Single-source files should always be prefixed with an underscore, and more or less follow the [same naming conventions as our style guide](https://docs.validmind.ai/about/contributing/style-guide/conventions.html#filenames):
- e.g. `_collaborate-with-others-comments.qmd`
- Single-source files do not need a YAML header, and should not contain footnotes
- Single-source files are the only place where instructional inline links are preferred

{{< include _source-file.qmd >}}
14 changes: 7 additions & 7 deletions site/_quarto.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -292,13 +292,13 @@ website:
# - internal/testing.qmd
# - text: "---"
# - text: "EXPERIMENTS"
# - file: internal/css-grid/tachyons-grid.qmd
# - file: internal/footnotes/footnotes.qmd
# contents:
# - internal/footnotes/hover-only.qmd
# - internal/footnotes/margin-only.qmd
# - internal/footnotes/margin-hover.qmd
# - internal/footnotes/text-notes.qmd
# - file: internal/single-sourcing/destination-file.qmd
# - file: internal/footnotes/footnotes.qmd
# contents:
# - internal/footnotes/hover-only.qmd
# - internal/footnotes/margin-only.qmd
# - internal/footnotes/margin-hover.qmd
# - internal/footnotes/text-notes.qmd

page-footer:
background: "#DE257E"
Expand Down