Open source, {re}explained.
How it works, how to contribute, how to run your own project.
A free guide, articles and a showcase by the Open {re}Source community.
Open {re}Source website · Discord
"openresource.dev" is the repository containing the code source deployed to https://openresource.dev.
All commands are run from the root of the project, from a terminal:
| Command | Action |
|---|---|
npm install |
Installs dependencies |
npm run dev |
Run the development server at localhost:4321 |
npm run build |
Build your production site |
npm run astro ... |
Run CLI commands like astro add, astro check |
npm run astro -- --help |
Get help using the Astro CLI |
npm run vercel |
Run in the same conditions as Vercel |
npm run update:showcase |
Run the showcase script to gather GitHub and GitLab links from https://github.com/orgs/Open-reSource/discussions/3 (other links are ignored) |
npm run test |
Run the tests |
npm run shot -- <url> --out <name> |
Take a screenshot for the guide or an article (see Screenshots) |
npm run prettier:check |
Run Prettier to check the code style |
npm run prettier:write |
Run Prettier to fix the code style |
npm run spellcheck |
Spell-check the content; add real words to cspell.json |
npm run links |
Check internal links and anchors in the last build (needs lychee) |
npm run status |
Print a table of the guide's chapters: status, words, images, last update, reading time |
Screenshots are taken the same way every time with npm run shot: a 1440×900 viewport at 2×, no browser chrome, saved to public/images/ at 1440px wide max, as PNG or WebP when the PNG would be over 300 KB. It uses Playwright's Chromium (npx playwright install chromium the first time).
npm run shot -- https://github.com/mdn/content/contribute --out contributing-finding-open-source-projects-1 --clip main --box 'a:has-text("Read the contributing guidelines")' --box 'main a:text-is("good first issue")'| Option | What it does |
|---|---|
--out <name> |
File name in public/images/, without extension: <module>-<chapter>-<n> for the guide, <article>-<n> for articles |
--clip <selector> |
Capture only this element |
--box <selector> |
Draw a box around each match, numbered when there are several (repeatable) |
--theme dark|light |
The page's color scheme, dark by default. Boxes are gold on dark, dim cyan on light |
--wait <ms> |
Wait after the page is loaded |
For GitHub pages that need an account, set GH_SESSION to the value of your user_session cookie on github.com. tests/images.test.ts fails on images over 1440px wide, over 1 MB, or PNGs over 300 KB.
tests/prose.test.ts runs with npm run test and fails on:
- banned phrases: "In this chapter, we will", "In conclusion", "It's important to note", "Remember,", "essential", "crucial", "vibrant", "thriving", "delve", "landscape", "journey", "empower", "leverage", "In the simplest terms", "Here are some", "created equal", "Familiarize yourself with",
- an "Introduction" or "Conclusion" heading,
- a second
<p class="lead">in a page (a closing recap), - more than one exclamation mark in a page,
lastUpdate:instead oflastUpdated:in the frontmatter.
Code blocks, inline code and URLs are skipped. Pages written before these rules are listed in tests/prose.baseline.json with their current counts: a count can go down, never up. After fixing a page, lower or remove its entry, or regenerate the file:
UPDATE_PROSE_BASELINE=1 npm run test -- --run proseHave a bug or a feature request? Please first search for existing and closed issues. If your problem or idea is not addressed yet, please open a new issue.
Please read through our contributing guidelines.
Get an update on Open {re}Source's development and chat with the project maintainers and community members:
- Follow @open_resource on X.
- Follow @openresource on Mastodon.
- Follow @openresource.dev on Bluesky.
- Follow @openresource on Threads.
- Follow @open-re-source on LinkedIn.
- Explore our GitHub Discussions.
- Chat with the community and the maintainers on our Discord channel.
- Use our RSS feed to know when articles are out!
Code released under the MIT License.
Content (including images) released under CC BY-NC-SA 4.0:
publicdirectorysrc/assetsdirectorysrc/contentdirectory
The Open {re}Source mark, favicons and artwork (src/brand, src/assets/resources and public/covers directories, .github/header.*) are not covered by these licenses: all rights reserved.
