WIP: proof-of-principle-reusable-docs #9

Closed
adina wants to merge 2 commits from proof-of-principle-reusable-docs into trunk
adina commented 2025-07-09 09:33:30 +00:00 (Migrated from hub.psychoinformatics.de)

This PR is a replica of https://hub.psychoinformatics.de/adina/rdm.sfb1451.de/pulls/1 and demonstrates how to include a dataset with reusable documentation snippets (for now - temporarily - living at https://hub.psychoinformatics.de/adina/docs-template) via hugo relearn-theme's "include" shortcode.

The process is:

  • add the dataset as a subdataset under shortcodes/include
  • reference a specific snippet (a markdown file) in the dataset in an existing file with a relative path like this:
{{%  include file="shortcodes/include/content/datalad/what-is-datalad.md" %}}

Why? This would allow us to extract generic documentation pieces and provide and maintain them centrally. Documentation for individual projects (e.g., consortia) can then use these centrally maintained resources. This should reduce maintenance efforts as updates can simply be pulled in once. Nevertheless, it allows for flexibility and customization, provided the generic snippets are small-scoped enough.

This PR is a replica of https://hub.psychoinformatics.de/adina/rdm.sfb1451.de/pulls/1 and demonstrates how to include a dataset with reusable documentation snippets (for now - temporarily - living at https://hub.psychoinformatics.de/adina/docs-template) via hugo relearn-theme's "include" shortcode. The process is: - add the dataset as a subdataset under shortcodes/include - reference a specific snippet (a markdown file) in the dataset in an existing file with a relative path like this: ``` {{% include file="shortcodes/include/content/datalad/what-is-datalad.md" %}} ``` Why? This would allow us to extract generic documentation pieces and provide and maintain them centrally. Documentation for individual projects (e.g., consortia) can then use these centrally maintained resources. This should reduce maintenance efforts as updates can simply be pulled in once. Nevertheless, it allows for flexibility and customization, provided the generic snippets are small-scoped enough.

Pull request closed

Sign in to join this conversation.
No reviewers
No labels
No milestone
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
sfb1451-inf/rdm.sfb1451.de!9
No description provided.