How to Contribute

Thanks for thinking of contributing to Leaning Technologies open source projects and their documentation!

Quick links:

Your First Pull Request

Working on your first pull request? You can learn how here:

How to Contribute to an Open Source Project on GitHub

Bugs and Feature Requests

If you find a bug or have a feature request, please open an issue on the relevant repository or ask in the #support channel on our Discord server.

Documentation

Documentation is written in Markdown and MDX and is located in the src/content/docs directory of Labs.

Style guide

In brief:

  • Use Diataxis for structure
  • Be concise but thorough; you can always link to more information or provide it in a callout
  • Always use examples
  • Avoid “I” and “you”; use “we” if necessary

Labs

Labs is the codebase for the Leaning Technologies developer site. It is built using Astro, Tailwind, TypeScript, and Svelte.

Setup

  1. Install Node.js
  2. Install pnpm
  3. Clone the repo, e.g. with gh clone leaningtech/labs
  4. Change into the directory: cd labs
  5. Install dependencies: pnpm install
  6. Spawn development server: pnpm start
  7. Visit localhost:4321

Linting

Linters run automatically in this GitHub Action workflow. You can also run them locally.

lychee is a tool that recursively checks all links on the site for 404s.

  1. Install lychee
  2. Build the site: pnpm build
  3. Preview the site in the background: pnpm preview --host 0.0.0.0 &
  4. Run lychee: lychee dist src/content

You may need to set GITHUB_TOKEN to avoid issues checking links to github.com.

Prose

Vale checks style and grammar in Markdown files, like capitalisation of certain words, use of passive voice, and more.

  1. Install Vale
  2. Download style rules: vale sync
  3. Check with Vale: vale .

For editor integration, use:

Vale is quite brittle, particularly on MDX files. It’s okay if there are errors, but please look at them to see if they are valid. Hopefully we can improve this in the future.

Prettier

Prettier is a code formatter. It’s shipped as a devDependency, so pnpm install will have installed it.

To format all files:

Terminal window
$ pnpm format

Astro diagnostics

Astro has some of its own diagnostics.

Terminal window
$ pnpm astro check

TypeScript

Terminal window
$ pnpm tsc
Was this page helpful?
Suggest changes