Skip to content

Conversation

@dseynaev
Copy link

This PR adds support for supplying repository links via a Hugo data file next to the builtin GitHub support. The idea is to enable more complex workflows by separating out the task of generating the links and leaving it to the user:

  • support literate programming workflows: tools like Rmarkdown can be easily chained with Hugo in a CI system by writing dynamically generated markdown in the content directory of Hugo. However in this case the true source is different than the one seen by Hugo so the Docsy links will point to the wrong files.

  • support multi-repository sites. In large projects it may be desirable to distribute the site sources over multiple repositories e.g. for access control reasons but still aggregate everything to a single site (e.g. with git submodules which break the links)

By using Hugo data files YAML, JSON and TOML are all supported.
TOML example:

['docs/Concepts/_index.md']

editPageURL = "https://my/test/edit/link"
newPageURL = "https://my/test/child/link"
issuesURL = "https://my/test/doc/issue/link"
projectIssuesURL = "https://my/test/project/issue/link"

As a bonus, this also provides an escape hatch for non-GitHub hosted repositories. The documentation states:

Currently Docsy supports only GitHub repository links “out of the box”. If you are using another repository such as Bitbucket and would like generated repository links, feel free to add a feature request or update our theme.

this PR provides an alternative approach by allowing users to generate the links for whatever git server in CI

@LisaFC
Copy link
Collaborator

LisaFC commented Apr 1, 2021

Ooh, this is a nice feature! Could you add some documentation for it to https://www.docsy.dev/docs/adding-content/repository-links/?

@google-cla google-cla bot added the cla: yes Indicates the PR's author has signed the CLA. label Jun 25, 2021
@dseynaev
Copy link
Author

dseynaev commented Jun 25, 2021

Rebased because of a recent conflict. @LisaFC I noticed there is some scope overlap with the recently added github_url feature. I still think the datafile approach is useful since automatically generating links in CI would not involve parsing the page metadata. Thoughts?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cla: yes Indicates the PR's author has signed the CLA.

2 participants