Contributing
If you want to contribute to Nushell itself, see nushell/nushell/CONTRIBUTING.md and the contributor-book.
If you want to contribute to the Nushell documentation and website, this is the right place.
While most documentation is updated via commits to this repository, an important exception is the help
documentation for all commands. These pages are generated automatically from the internal help in each command's .rs
file. Please see the main Nushell repo and submit pull requests for changes to command documentation there.
Local Development
This website is based on VuePress.
Getting started
One-time Setup
Clone the doc repo locally:
git clone git@github.com:nushell/nushell.github.io.git nu-docs
Install Node.js (minimum version required: v18.12.0)
Run
npm install
in the root of the local repo after cloning to install the required dependencies for the dev server. This will also be necessary if any dependencies change.
For each group of changes
Sync your fork on GitHub
git pull
the latest changesRun
npm run dev
Pay close attention to the messages when starting the server, as this will inform you of any broken links and other errors that might need to be fixed.
Create a branch for your changes using a short, descriptive name:
git checkout -b my_changes
If you're adding a new page to the book, to make it appear, put it also to
.vuepress/configs/sidebar/{locale}.ts
.Make changes
Verify your local changes render correctly by opening http://localhost:8080/ in a web browser and navigating to the new or changed pages
Commit and push your changes
git commit -m "Commit Message" git push --set-upstream origin my_changes
(Where
my_changes
is the current branch)Create a pull request in this GitHub repo
Enabling a Preview URL From Your Fork
Just enable GitHub actions in your repo settings. That's all! It will start deploying the next time you push to main
.
Display Nu Code Snippets With Syntax Highlighting
To display Nushell code snippets with syntax highlighting support you can wrap the Nu codes with ```nu ```
or ```nushell ```
, for example:
```nu
# List the top five largest files
ls | where type == file | sort-by -r size | first 5
```
The preferred form for consistency is ```nu
.
Translation Guide
Follow the steps above for each group of translations.
Adding to or updating existing translations
Check outdated translations. A helper script is provided for this. From the repository root, run:
nu tools/i18n.nu outdated zh-CN
This will provide a list of all files that have been changed or added since the last translation update for the specified locale.
Creating a new translation
Add a book dir for the specified locale in the docs' root folder, say
zh-CN
.Create a
book
child folder for all your translated documents and a README.md for the home page of your localeModify the VuePress config file
.vuepress/config.js
and addzh-CN
related configs.Here is an example commit for reference.
Add a
README.md
in thebook
dir which will be the default introduction page of Nushell.Important
Please DO NOT translate the file name of the docs.
Run
npm run dev
, then open http://localhost:8080/ in your browserSwitch to the language you are going to translate into, and you will see the introduction page you have just created. You can translate the docs and save them to get a preview in the browser.
Update the
i18n-meta.json
file by filling in the locale value of the doc you have just finished. It's recommended to usecommit_id@author
or simply acommit_id
to indicate your translation end to the specified commit.Commit your changes. It's recommended to squash all your commits in one commit with a commit message like this:
Translate your_doc_file.md to zh-CN from commit: f3dc86d3d
;Push your changes as documented above