sfb1451/rdm.sfb1451.de
2
0
Fork 1
Code Issues 1 Pull requests 1 Packages Activity Actions

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

Draft
adina wants to merge 2 commits from proof-of-principle-reusable-docs into trunk
pull from: proof-of-principle-reusable-docs
merge into: sfb1451:trunk
Conversation 0 Commits 2 Files changed 4 +11 -33
adina commented 2025-07-09 09:33:30 +00:00
Member
Copy link

This PR is a replica of adina/rdm.sfb1451.de#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.
This removes generic content from the documentation,
and in its place, links to documentation snippets
containing (almost) the same content via hugos
include shortcode. This commit is merely a demonstration
to test how having a generic documentation subdataset
looks and feels like.
This pull request has changes conflicting with the target branch.
  • content/datalad/help.md
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin proof-of-principle-reusable-docs:proof-of-principle-reusable-docs
git switch proof-of-principle-reusable-docs

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch trunk
git merge --no-ff proof-of-principle-reusable-docs
git switch proof-of-principle-reusable-docs
git rebase trunk
git switch trunk
git merge --ff-only proof-of-principle-reusable-docs
git switch proof-of-principle-reusable-docs
git rebase trunk
git switch trunk
git merge --no-ff proof-of-principle-reusable-docs
git switch trunk
git merge --squash proof-of-principle-reusable-docs
git switch trunk
git merge --ff-only proof-of-principle-reusable-docs
git switch trunk
git merge proof-of-principle-reusable-docs
git push origin trunk
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
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/rdm.sfb1451.de!9
No description provided.