proof-of-principle-reusable-docs

adina commented

2025-07-04 14:48:31 +00:00

Owner

This is a test / demo PR. Originally, I wanted to do it against the source repository, but I lack the necessary permissions. In any case, this is merely to illustrate the general principle.

adina added 2 commits

2025-07-04 14:48:31 +00:00

[DATALAD] Added subdataset 7abac80cc6

demonstrate use of docs.template bba617c3e5

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.

msz commented

2025-07-08 10:34:17 +00:00

First-time contributor

Thanks for demonstrating this with examples!

I granted you collaborator (write) access to sfb1451/rdm.sfb1451.de -- I don't have write access to www/rdm.sfb1451.de (which AFAIK is a pull mirror of the former) either.

I only spent a short time looking into it, so this is not a complete evaluation but a set of first impressions:

OK, so this is using the include shortcode from the relearn theme.
The placement of the included contents under shortcodes/include does follow relearn's examples, but it confused me for a while (the intended semantics seems to be "things used by the include shortcode"; it is not layouts/_shortcodes which would be for shortcode definitions, so it is fine, but it sounds similar).
I wonder what makes more sense - to include shorter fragments which are potentially part of a page and more than one can be used per page (as in your example), or entire pages? I tried to do an "entire page" include with symlinks and it didn't work (AFAIK in some cases Hugo ignores symlinks) but I still wonder if there are other methods.

Thanks for demonstrating this with examples! I granted you collaborator (write) access to sfb1451/rdm.sfb1451.de -- I don't have write access to www/rdm.sfb1451.de (which AFAIK is a pull mirror of the former) either. I only spent a short time looking into it, so this is not a complete evaluation but a set of first impressions: - OK, so this is using the [include shortcode](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/include/) from the relearn theme. - The placement of the included contents under `shortcodes/include` does follow relearn's examples, but it confused me for a while (the intended semantics seems to be "things used by the include shortcode"; it is *not* `layouts/_shortcodes` which would be for shortcode definitions, so it is fine, but it sounds similar). - I wonder what makes more sense - to include shorter fragments which are potentially part of a page and more than one can be used per page (as in your example), or entire pages? I tried to do an "entire page" include with symlinks and it didn't work (AFAIK in some cases Hugo ignores symlinks) but I still wonder if there are other methods.

adina commented

2025-07-08 10:42:13 +00:00

Author

Owner

I granted you collaborator (write) access to sfb1451/rdm.sfb1451.de -- I don't have write access to www/rdm.sfb1451.de (which AFAIK is a pull mirror of the former) either.

Thank you!

Sorry for the lack of context in this PR. It came from reading the RFD and chat messages that led to it, but all of that info was only in my head when I should have put it in the PR description. ;-)

Re placement: I recall fiddling with it and hugo's path semantics for a while in the past. I'm sure other placements would work as well, but I prefer staying close to the documentation/examples.

Re length of includes: I think it is more difficult to write entire pages in a way that they can be included. I found that often there are generic pieces that are suitable for reuse, but they need additional custom-ness from the docs at hand. Whats also difficult is that the content can only be markdown, the necessary meta data (e.g., weight, date) of hugo pages is parsed "verbatim" - I guess that would be a technical hurdle, at least for including pages via the "include" shortcode.

> I granted you collaborator (write) access to sfb1451/rdm.sfb1451.de -- I don't have write access to www/rdm.sfb1451.de (which AFAIK is a pull mirror of the former) either. Thank you! Sorry for the lack of context in this PR. It came from reading the RFD and chat messages that led to it, but all of that info was only in my head when I should have put it in the PR description. ;-) Re placement: I recall fiddling with it and hugo's path semantics for a while in the past. I'm sure other placements would work as well, but I prefer staying close to the documentation/examples. Re length of includes: I think it is more difficult to write entire pages in a way that they can be included. I found that often there are generic pieces that are suitable for reuse, but they need additional custom-ness from the docs at hand. Whats also difficult is that the content can only be markdown, the necessary meta data (e.g., weight, date) of hugo pages is parsed "verbatim" - I guess that would be a technical hurdle, at least for including pages via the "include" shortcode.

adina referenced this pull request from sfb1451/rdm.sfb1451.de

2025-07-09 09:33:30 +00:00

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

adina commented

2026-04-24 11:55:24 +00:00

Author

Owner

I'm giving this PR a ping. It was a proof-of-principle PR with only minor changes to demonstrate the "reusable documentation snippets". The actual docs have worked since and got updates also - as did the documentation snippets. This PR definitely needs to be updated before getting merged (which I'm happy to do). @msz do you have a preference whether I should update this PR and add more along the same line, or close this?

msz commented

2026-04-24 16:33:19 +00:00

First-time contributor

Thanks for the reminder - that required going back in time... I remember this: the proof of principle definitely worked, but I was skeptical whether replacing individual paragraphs with references to text that comes from another repo is a tangible improvement in maintainability (perhaps irrationally, because now I recall the feeling but I don't feel it now looking at the diff).

If you feel that the concept still works and want to expand it then I won't block the PR, but given that the snippets system is about maintainability and that this repo is basically static now (one commit in last 8 months) I would instead propose that we PR and that I remember it the next time a time for updates comes.

Thanks for the reminder - that required going back in time... I remember this: the proof of principle definitely worked, but I was skeptical whether replacing individual paragraphs with references to text that comes from another repo is a tangible improvement in maintainability (perhaps irrationally, because now I recall the feeling but I don't feel it now looking at the diff). If you feel that the concept still works and want to expand it then I won't block the PR, but given that the snippets system is about maintainability and that this repo is basically static now (one commit in last 8 months) I would instead propose that we PR and that I remember it the next time a time for updates comes.

👍 1

adina closed this pull request

2026-04-24 19:34:06 +00:00

Pull request closed

Please reopen this pull request to perform a merge.

Rows
Columns

proof-of-principle-reusable-docs #1

Pull request closed