- ⚖️ NEAR Protocol is a new smart-contract platform that delivers scalability and usability.
- 🛠 Through sharding, it will linearly scale with the number of validation nodes on the network.
- 🗝 Leveraging WebAssembly (via Rust and AssemblyScript), more sane contract management, ephemeral accounts and many other advancements, NEAR finally makes using a blockchain protocol easy for both developers and consumers.
Check out the following links
- Deployed, live documentation: https://docs.near.org
- Example applications: https://near.dev
- Community chat: https://near.chat
NEAR uses Docusaurus for documentation. Please refer to their documentation for details on major structural contributions to the documentation.
For simple content changes you have 2 options
- Submit an issue
- Submit a pull request (we prefer PRs of course)
This is the fastest way to submit content changes directly from the page where you notice a mistake.
- Open any page in the docs on https://docs.near.org
- Click the
[ Edit ]
button at the top right hand side of every content page - Make your edits to the document that opens in GitHub by clicking the ✎ (pencil) icon
- Submit a PR with your changes and comments for context
This is the standard fork-branch-commit workflow for submitting pull requests to open source repositories
-
Fork this repo to your own GitHub account (or just clone it directly if you are currently a member of NEAR)
-
Open your editor to the top level repo folder to view the directory structure as seen below
-
Move into the
/website
folder where you will run the following commands:-
Make sure all the dependencies for the website are installed:
# Install dependencies yarn
-
Run the local docs development server
# Start the site yarn start
Expected Output
# Website with live reload is started LiveReload server started on port 35729 Docusaurus server started on port 3000
The website for docs will open your browser locally to port
3000
-
-
Make changes to the docs
-
Observe those changes reflected in the local docs
-
Submit a pull request with your changes
Your project file structure should look something like this with a few key files and folders highlighted
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE-APACHE.txt
├── LICENSE-MIT.txt
├── README.md <-- the document you are reading right now
├── docs <-- all the content for the site is in this folder as markdown files
│ ├── api
│ ├── assets <-- place documentation images here
│ ├── code-patterns
│ ├── community
│ ├── concepts
│ ├── contribution
│ ├── development
│ ├── hackathon
│ ├── interaction
│ ├── local-setup
│ ├── overview
│ ├── quick-start
│ ├── roles
│ ├── style-guide.md
│ ├── technical
│ ├── tutorials
│ └── validator
└── website
├── build
├── core
├── i18n
├── package.json
├── pages
├── sidebars.json <-- rarely used for changing left-hand-side page navigation
├── siteConfig.js <-- rarely used for general site configuration (including header links)
├── static
└── test-links.sh <-- always used to test links before submitting changes
For broken links internal to the docs, please submit an issue or PR request as per above.
If you found a broken link from a Google search, please request to remove it from their index here: https://www.google.com/webmasters/tools/removals
Contributors, please consider checking for broken links executing the file test-links.sh
before pushing to this repo so our CI doesn't fail, forcing someone (maybe you) to fix broken links before merging.
Here's one way to always make this happen automatically on every push:
Note that the file
test-links.sh
mimics the CI build script by checking all links then cleaning itself up.
- Create a new githook in your local copy of the repo called
.git/hooks/pre-push
and copy the entire contents of the snippet below into that file.- Now every time you try to push to the repo, links will be checked for you automagically.
#!/bin/sh set -e echo "Push detected in NEAR docs repo" if [[ $NEAR__CHECK_ALL_LINKS ]] # only stop and check all links if this is enabled # since it request npm installed (uses npx) and can generally be surprising to new contributors then echo "Checking all links before push" GIT_DIR=$(git rev-parse --show-toplevel) cd "$GIT_DIR/website" ./test-links.sh else # just let them know there's a way to do this before every push echo "export NEAR__CHECK_ALL_LINKS=1 to check all links before pushing" echo fi