Skip to content

a refactoring idea to rewrite the README #814

@amtoine

Description

@amtoine

hello there 👋 😋

i feel this website repository is mainly made for developers or people who click on the "Edit this page on GitHub" button in the footer.

the other day i was looking for contribution guidelines and ended up asking how to run the website locally on the discord...
i did not see the CONTRIBUTING.md file in the root of the repo 😭

in fact, i looked at the main README, looking for instructions but found none => this is because the main ./README.md file IS the
english frontpage of www.nushell.sh!

my idea

i propose to move the frontpage of the website to some other place than ./README.md and write a true development-oriented README.md
to:

  • point to the website itself at www.nushell.sh
  • point to the main nushell repo
  • explain in details how to contribute to this repo OR at least explicitely point to CONTRIBUTING.md

some details

  • i think the paths to all the pages MD files are specified in .vuepress/configs/, right?
  • i propose to move blog/, book/, commands/, contributor-book/ and cookbook/ to a new en/ directory, leading to the following architecture:
.
├── CNAME
├── CONTRIBUTING.md
├── i18n-meta.json
├── i18n.nu
├── LICENSE
├── make_docs.nu
├── package.json
├── package-lock.json
├── README.md
├── assets/
├── de/
├── es/
├── en/
├── ja/
├── pt-BR/
├── snippets/
├── tr/
└── zh-CN/

and one more level details

.
├── CNAME
├── CONTRIBUTING.md
├── i18n-meta.json
├── i18n.nu
├── LICENSE
├── make_docs.nu
├── package.json
├── package-lock.json
├── README.md
├── assets
│   └── images
├── de
│   ├── README.md
│   └── book
├── es
│   ├── README.md
│   ├── book
│   └── contributor-book
├── en
│   ├── blog
│   ├── book
│   ├── commands
│   ├── contributor-book
│   └── cookbook
├── ja
│   ├── README.md
│   └── book
├── pt-BR
│   ├── README.md
│   ├── book
│   └── contributor-book
├── snippets
│   ├── installation
│   ├── introduction
│   └── moving_around
├── tr
│   ├── README.md
│   └── book
└── zh-CN
    ├── README.md
    └── book

that way

  • the english default channel would be just another language channel, even though the prefered one by default
  • the repo would have a more homogenous structure
  • we would be able to move the english frontpage from README.md to en/README.md, as with the other languages
  • we would be able to write a true README for the website repo

i wanted to have some feedback before trying to refactor the website like this.
shouldn't be that much work, mainly changing paths, but ehe 😉

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions