nushell / nushell/nushell.github.io

a refactoring idea to rewrite the `README`

Open
#814 2 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
258
Forks
561
Avg merge
3h 20m
Merged PRs (30d)
15

Description

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 πŸ˜‰

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up β€” it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with README.md, CONTRIBUTING.md, and the path definitions in .vuepress/configs/. Review how blog/, book/, commands/, contributor-book/, cookbook/, and the language directories are referenced before proposing the move. Done means the repository has a development-oriented README, the English content is under en/, and all documented paths remain consistent.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation, internationalization
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
32/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.