Skip to content
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.

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

allow repository links to be provided through a data file #492

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

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.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants