Improve how we handle `Edit this page on GitHub` link in documentation

[derberg]

Current state

This is the code responsible for rendering edit link: https://github.com/asyncapi/website/blob/master/components/layout/DocsLayout.js#L19-L24

so it is basically "hardcoded" link that depends on post.slug.includes info passed to next.js during build

Problem

Now all docs are located in website. Actually wrong, all docs are here, but some are not authored here, but these are just a copy of files from other repos.

Example: specification files come from spec repo, this is why code has this:

if (post.slug.includes('/specifications/')) {
    return <a target="_blank" rel="noopener noreferrer" href={`https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md`} className="ml-1 underline">Edit this page on GitHub</a>
  } 

To render different link to the spec edit. Side note: it is anyway broken now as current slug is specification without s.

This is not the best way to do it long term as now when we also have Generator docs https://www.asyncapi.com/docs/tools/generator we would have to add there another if. This or next week we will also have CLI docs in website, and it means we need to add another if

Requirement

Docs are pushed from other repos using GitHub action. Maintainers of other repositories should not be forced to open PRs in website to enable something. So it should be easy to specify what is the edit link for any project with some script.

For example now, automation in the generator is even able to create _section.md file -> https://github.com/asyncapi/generator/blob/master/.github/workflows/update-docs-in-website.yml#L41

It should be also that easy to provide what is the base link to Edit this page on GitHub

Proposal

I think best would be to introduce another config file in https://github.com/asyncapi/website/tree/master/config This file would contain a map of slug vs link. In other words, generator maintainer can specify:

tools/generator https://github.com/asyncapi/generator/tree/master/docs
reference/specification https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md

Above I suggest simple non-json structure as it will be easier to add new lines from the CI/CD script perspective.

• First value is slug and what edit link it should match
• If link do not points to specific markdown file then it means it is dynamic and in the UI, to the link /{post.slug}.md should be added

What do you think?

cc @alequetzalli

[quetzalliwrites]

Fully AGREE we need to fix this issue for docs authored outside of /website repo; I just need a little extra help fully digesting everything explained in this issue proposal. 😄

[derberg]

@alequetzalli when we generate AsyncAPI website to put it on netlify, docs from generator/cli and others are already there. Website have no idea where they came from.

This is why for now we have this hack:

if (post.slug.includes('/specifications/')) {
    return <a target="_blank" rel="noopener noreferrer" href={`https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md`} className="ml-1 underline">Edit this page on GitHub</a>
  } 

but we should not rely on hack anymore, as Generator is there now, CLI will be soon, and then others in the future.

so we need a way to let website know, from Generator and any other tool workflow, that the docs that we sent come from Generator for example are located in https://github.com/asyncapi/generator/tree/master/docs (and this link we use in edit button later)

---

After christmas I change my mind, we can have JSON structure. It will be easier to read in the react code in website. And we can always edit it in GitHub action using custom JS code.

new edit-button-config.json config file would looks like:

{
    "tools/generator": "https://github.com/asyncapi/generator/tree/master/docs"
    "reference/specification": "https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md"
}

slug would be the key, as it is always unique and will be easier to pick up + and the value is the link to use

@magicmatatjahu @fmvilas @akshatnema any objections?

[akshatnema]

@derberg I agree with the approach you specified above but only concerned with the edit-button-config.json file, whether it will be managed manually or it is automated. Rest is perfectly fine and I'll look into the implementation for more clarification if needed.

[arunavabasucom]

can i work on this issue ??

[derberg]

@akshatnema

edit-button-config.json

should be managed through automation. So basically whoever maintains generator, cli or other tools, is not obligated to open any PR to website manually.

@arunavabasu-03

yes please

[quetzalliwrites]

thanks for the long reply and extra detail @derberg! I get it now and the need for this improvement...

I have no opinions on the technical implementation and will leave that for community members better suited to this implementation work 😄

[sambhavgupta0705]

Hi @akshatnema ,I would like to work on this issue.

[derberg]

@arunavabasu-03 can you confirm if you work on this? so @sambhavgupta0705 knows if he can pick up instead?

[arunavabasucom]

goahead @sambhavgupta0705 !! @derberg i currently working on the recent assigned issue !!

[sambhavgupta0705]

ok @arunavabasu-03