2b1a5072d7 | ||
---|---|---|
.. | ||
components/global | ||
content | ||
public | ||
.env.example | ||
.gitignore | ||
README.md | ||
app.config.ts | ||
app.vue | ||
netlify.toml | ||
nuxt.config.ts | ||
package.json | ||
tokens.config.ts | ||
tsconfig.json | ||
types.ts |
README.md
Welcome to the Elk Docs
The documentation site publishes to https://docs.elk.zone. We use Docus as the site generator and deploy through Netlify.
Quickstart
Prerequisites
- Github account
- Git installed on your machine
- Node >14.18 installed
- Use
node -v
to see which version you have installed. - Use
nvm install node
to upgrade to the latest version. - Refer to the nvm docs for information on installing
nvm
.
- Use
- pnpm installed
Install and Preview
- Fork the Elk Github project into your own account
- Clone your fork to your local machine
- From your terminal,
cd
to the directory you cloned into cd docs
to enter the docs folder- Run
npm install
Note: Run this from the project'sdocs
folder, not the root of the repository on your machine! - Run
npm run dev
to launch a preview - Visit
localhost:3000/docs/
to see a live preview of the docs
Contributing
When you are ready to submit work back to the main Elk repo, create a PR.
- If it has been a bit, synchronize your fork with the upstream repo on Github.
- Do your work in a branch on your fork
Use
git checkout -b branchNameToUse
to create a working branch separate frommain
. - Do your work in your preferred editor
- Commit changes often and write meaningful commits
- Push the changes from your local machine to your fork on Github
- Go to your fork of the Elk project in your Github account
- Select the Pull Request tab
- Select New Pull Request
- Confirm the repo/branches to compare
- Base repo should be elk-zone/elk
- base branch should be main
- Head repository should be your fork
- Compare branch should be your working branch you want to submit If you don't see four drop downs, be sure you are comparing across forks.
- Add a description of the changes your request makes
- Select Add Pull Request
Other team members will review your PR and make comments or suggestions through the PR. You can continue making additional changes and/or apply feedback by making additional commits to the branch on your fork. ALWAYS WORK IN YOUR FORK/BRANCH.
Writing
Tips
- Docs are in the
docs/content
folder - Write in standard markdown
- Refer to the Docus writing pages guide
- Docus provides additional components to extend basic markdown
Avoid screenshots until Elk reaches a stable release.
Standards
Write in American English using spelling as found in Merriam Webster. Translation and localization will be handled separately as/when availability or necessity allow.
Use semantic linefeeds with no more than one sentence per line. To create paragraphs, use a blank line.
There are no house style rules currently. When we add any, they will be found in this document.
Style Guides
Use the first guide that mentions a usable standard from the order below:
- Refer to the U.S. Government's Federal Plain Language Guidelines as a base standard.
- For user interface, device, and other technical guidance, refer to Google's Developer Style Guide.
- As a secondary reference to the Google guide, refer to Microsoft's Style Guide, then the Chicago Manual of Style, 17th Edition.
We use Merriam-Webster as the standard dictionary for spelling.
Images
Place image files in the /docs/public/images folder. You can create subfolders to organize the images.
To add an image to a doc, use standard markdown with alt text:
[![Alt text](/docs/images/image.svg)](URL.for.hyperlink)
[![StackBlitz logo](/docs/images/stackblitz.svg)](https://stackblitz.com/)
In-house Styles
None yet defined