Fix edit links of modules

[srid]

Docusaurus is not flexible enough to allow overriding edit links en masse at folder level.

See https://zero-to-flakes.com/haskell-flake/examples - where the edit link is broken.

We can workaround this by patching the YAML frontmatter of all .md files in CI, during site build.

[brsvh]

An alternative solution is override the default EditUrlFunction, with a check of whether the first line content of the file pointed to by docPath constitutes a path. This way appears to be less strenuous and is confined solely to the building process.

[brsvh]

with a check of whether the first line content of the file pointed to by docPath constitutes a path.

I had a quick look earlier and I didn't notice that it was actually a symbolic file.

I created an override function and it works on my local.

https://github.com/brsvh/zero-to-flakes/blob/29a9b48b7f428fec85d6555f2b78b0666c3c8e32/docusaurus.config.js#L54-L72

Do you think that's a clean solution?

[srid]

I created an override function and it works on my local.

https://github.com/brsvh/zero-to-flakes/blob/29a9b48b7f428fec85d6555f2b78b0666c3c8e32/docusaurus.config.js#L54-L72

Looks good. I don't write much JavaScript, so can't tell you if there is a cleaner solution. But maybe put it as a separate function with clear documentation comment on top. Happy to accept this as PR.

[srid]

@brsvh I just realized this. Your PR produces a view URL, but we want edit url.

For eg., go to https://zero-to-flakes.com/haskell-flake/start and click on Edit.

• It takes you to https://github.com/srid/haskell-flake/blob/d3c8d8be31d3a5dcf9d49e9dacfc570b5c736658/doc/start/start.md
  • The edit link is grayed out because of commit hash in the URL
• But we want the link to go to https://github.com/srid/haskell-flake/edit/master/doc/start/start.md

[srid]

I took a stab at improving the situation so now the user is at least taken to the default branch view URL where the edit link is no longer grayed out. But this TODO remains,

https://github.com/juspay/zero-to-flakes/blob/0250992a792dd6a18cecc9b7f94ce6977ea274b8/docusaurus.config.js#L74-L78

[brsvh]

• It takes you to https://github.com/srid/haskell-flake/blob/d3c8d8be31d3a5dcf9d49e9dacfc570b5c736658/doc/start/start.md

  • The edit link is grayed out because of commit hash in the URL

• But we want the link to go to https://github.com/srid/haskell-flake/edit/master/doc/start/start.md

I forgot to mention earlier that I use commit HASH instead of hardcoding master or main due to the updates occurring in my local submodules after executing just update. This led me to think that the project implies a fixed version of the document. However, I hold no particular stance on defaulting to construct a URL based on master.

I took a stab at improving the situation so now the user is at least taken to the default branch view URL where the edit link is no longer grayed out. But this TODO remains,

https://github.com/juspay/zero-to-flakes/blob/0250992a792dd6a18cecc9b7f94ce6977ea274b8/docusaurus.config.js#L74-L78

About this part, I think potential issues falling into two categories:

1. The inability to ascertain the default branch for those not using main or master, or specific branches.
2. For those not utilizing GitHub or GitLab, their editURL would not works.

However, most projects in the Nix realm are currently hosted on GitHub, so it's possible that I have over-engineered it.

If you still intend to maintain a singular document instance, I intend to enhance this when time permits. My current plan is to augment the parsing of .gitmodules to provide a map with more comprehensive information.

{
  path: 'ext/example/test',
  url: 'https://github.com/example/test.git',
  owner: 'example',
  repo: 'test',
  forge: 'github',       // `gitlab', other forge or `unknown`
  hash: COMMIT_HASH,
}

Then check what the default branch of the origin repository is based on the forge, something like this:

if (gitmodule['forge'] == 'github') {
  const defaultBranch = (async () => {
    const owner = gitmodule['owner']
    const repo = gitmodule['repo']
  
    try {
      const response = await fetch(`https://api.github.com/repos/${owner}/${repo}/branches`);

      if (!response.ok) {
        throw new Error('something wrong.');
      }

      const data = await response.json();
      const defaultBranch = data.find(
        branch => branch.name === data[0].name
      );
    } catch (error) {
      console.error('Error:', error.message);
    }
  })(); 
} else if (gitmodule['forge'] == ...) {
  ...
} else { ... }