gnolang / awesome-gno

Curated list of great GNO resources by the community.
https://gno.land/
Creative Commons Zero v1.0 Universal
55 stars 25 forks source link

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

Open yassinouider opened 1 year ago

yassinouider commented 1 year ago

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:

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 commented 1 year ago

I had a look at the website. Looks great! :heart_eyes:\ 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 commented 1 year ago

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 commented 11 months ago

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