Feature Request: Shortcode to Retrieve Code from Remote Git Repository

[zigmd]

Feature Description

Fetching code from a remote repository like GitHub, GitLab, Codeberg, etc. is a very useful shortcode.

Embedding pieces of code in markdown makes it tougher to document a webpage. Having this feature in Hextra natively will ensure better documentation.

An existing implementation can be found here:
#26

---

Problem/Solution

People can fetch code maintained in a Git repository like (GitHub, GitLab, Codeberg, etc.) to complement their documentation.

Maintaining code and documentation together is a tedious task, and will exacerbate as the number of pages in the website increase.

---

Alternatives Considered

Yes, I'm currently using a custom shortcut, which I modified based on this suggestion:
#26

But it doesn't have a copy icon on the top right.

---

Additional Context

Received a suggestion in the Hextra's discussion a few weeks back:
#26

[imfing]

When it comes to code snippets, I'd typically recommend using Gist, especially since Hugo provides this shortcode as a built-in feature.

I appreciate the idea of fetching code directly from GitHub, and I understand the motivation behind your request – maintaining code and documentation together can be a challenging task. However, I have some reservations about how much a shortcode like this would fundamentally enhance our documentation.

There are a couple of considerations when it comes to dynamically pulling code from remote Git repositories:

• Rate limit: GitHub has a rate limit (60 requests per hour) for anonymous access to its APIs, and this limit can be easily reached
• Authentication: It can be tricky to pass in token under various environments
• API complexity: Different code hosting providers have varying API interfaces, and incorporating these into a shortcode might introduce additional complexity

People can fetch code maintained in a Git repository like (GitHub, GitLab, Codeberg, etc.) to complement their documentation.

I think a better approach is to maintain a submodule from the documentation repository, and create symbolic links or use similar shortcode to read the code content similar to #26.

I believe it's worth discussing this further in a dedicated thread where we can gather opinions and ideas from the community.

[zigmd]

When it comes to code snippets, I'd typically recommend using Gist, especially since Hugo provides this shortcode as a built-in feature.

• Gists are easy to maintain only if they are few in number. There could be cases where code could be fetched from a remote repository in a lot of pages.

• Moreover, the code that I'm fetching is part of a continuous integration pipeline. Gists, in my opinion, are not a good idea. They could either be plain text or code.

• Maintaining plain text in a website framework (like Hugo) makes more sense than doing it in a Gist. Maintaining code in a repository is better because a CI can be run (lint, build, test, etc.) on it which guarantees correctness of the code and makes the end user more confident. Maintaining code on gists is a bad idea.

• Here's a (formerly) popular example:

  You want to create documentation for creating an EC2 instance on AWS using Terraform, and you come up with this. If you notice some of the code blocks, they can be run in their entirety simply by copy and pasting. This is also true for other resources.

  For running a code block in its entirety, there needs to be some kind of CI. In this case you may do something like:

  terraform init
  terraform validate
  terraform fmt
  terraform plan -out ec2.tfplan
  terraform show ec2.plan > ec2.txt
  

  in different stages of the CI.

  When a user visits the webpage they can copy and paste things with a lot of confidence because the code well maintained.

---

I appreciate the idea of fetching code directly from GitHub, and I understand the motivation behind your request – maintaining code and documentation together can be a challenging task. However, I have some reservations about how much a shortcode like this would fundamentally enhance our documentation.

A technical documentations website has many code blocks on different pages. The person making the documentation would want the code to be well tested, so that users who copy it without running into any issues like build and test failures, etc. If the code block is well tested, end users will report fewer issues.

As a result that person may opt to run a CI for the code segments - like format, build, test, etc. and fetch them onto the website.

---

There are a couple of considerations when it comes to dynamically pulling code from remote Git repositories:

• Rate limit: GitHub has a rate limit (60 requests per hour) for anonymous access to its APIs, and this limit can be easily reached

It is unlikely that a number anywhere near this limit will be reached. The browser is going to cache the webpages and the maintainer is not going to be publishing at that rate.

• Authentication: It can be tricky to pass in token under various environments

The webpages in "repository-1" are public and so are the code blocks on "repository-2". Authentication is a really niche use case.

• API complexity: Different code hosting providers have varying API interfaces, and incorporating these into a shortcode might introduce additional complexity

The shot code in discussion #26 can be used to fetch raw content from any remote repository. I have tested it for GitHub and Codeberg, and I'm confident it will work work other vendors like GitLab, BitBucket, etc. as well.

If you notice the shortcode, there is nothing vendor specific. All it needs is a copy icon :)