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

Add automated generation of README and website with Github Actions #28

Closed

Conversation

yassinouider
Copy link

This pull request adds automatic generation of the README.md and website (GitHub Page) for the awesome-gno repository using GitHub Actions. This pull request addresses issue #24

The changes include the following:

  • Added a new entries.csv file to allow contributors to add new links.
  • Added a new categories.csv file to allow adding new categories.
  • Added a new staffpicks.csv file to highlight specific links.
  • Added generator script to read these files and generate the README.md and website/index.html files on every push with GitHub Actions.

Example website at https://yassinouider.github.io/awesome-gno
Example README at https://github.com/yassinouider/awesome-gno/blob/main/README.md

Before merging, it is necessary to update the repository settings in order to use GitHub actions as the source for the website.

@thehowl
Copy link
Contributor

thehowl commented Mar 13, 2023

I had a look at the website. Looks great! 😍
I'm going to make a very high-level list of first steps I think you could take, and points I think should be discussed:

  1. The scripts/github-generator directory probably belongs to the root directory, rather than being inside .github. I would even argue it deserves its top-level directory generator, or web
  2. I'm not particularly enthusiastic about having things in csv files which are then used for generation of the markdown and website. I'd rather it were a simple Markdown file in the README, and the website is a better rendering of that, from the first header onwards.
    So I propose this:
    • Ditch the csv files, and make the generator instead parse the README.md file.
    • The website is generated printing the Markdown (I propose using this instead of blackfriday, as it has a more idiomatic Go API). Paragraphs which only contain lists, in the form of <li><a href="...">...</a> - ...</li>, are automatically recognised, and reorganised to be in the same format you are currently rendering.
    • Paragraphs which don't contain lists in that format are just rendered as normal HTML.
    • The sidebar is generated as a normal TOC, on sections with items adding the number of them, and removing it on sections without items.
    • If the format of the README.md file is wrong, then the tool can exit and fail the action, saying a message like generator cannot parse README; adjust syntax or generator tool accordingly.
    • Maybe the warning above could also be thrown if a PR author updates the readme adding a new section but forgets to update the TOC, as a bit of a "linter" functionality.
  3. I'm not particularly sold on the "staff picks". Seeing as this is an official website, ideally the only way we can distinguish on the README between higher- and lower-quality resources is through the order; but what the "staff picks" are only the official resources and documentation. This is also because putting "Staff picks" next to Adena or onbloc's documentation grants more "officiality" and affiliation with the project than the project has or should have.
    I think it can make sense to move Adena Wallet as the first item in the "Tools" section, but personally I would ditch the "Staff picks" badge.
  4. I don't think the built website should be committed. So just generate and publish in a single step like in the docs, I would suggest.
  5. website/font/font.css mixes tabs and spaces, and should be indented properly. Also, is it necessary to have all of thin, light, normal and bold font-faces?
  6. Just a note: please don't separate lists in README in different paragraphs (ie. adding an empty newline between items).

@thehowl
Copy link
Contributor

thehowl commented Mar 15, 2023

I've also had a bit of a discussion with the core team today about how we could tackle this while having more metadata.

I think for now you can work with the instructions as above. A future idea in order to have more metadata and filtering would probably be to add a way in the README to add metadata after each item. For instance.

* [Quickstart Guide](https://test2.gno.land/r/boards:testboard/5) - How to start interacting with the blockchain.
<!--
tags:
  - guide
  - official
  - testnet
author: core-team
date: 2022-07-13
-->

This doesn't need to be implemented now, but I think it's useful to keep in mind as a future direction.

@waymobetta
Copy link
Contributor

@yassinouider It's been about 4 months; have you had a chance to review and incorporate the above feedback?

@leohhhn
Copy link
Contributor

leohhhn commented Sep 17, 2024

Closing due to no activity.

@leohhhn leohhhn closed this Sep 17, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants