{"id":15045929,"url":"https://github.com/denoland/docs","last_synced_at":"2025-10-04T06:19:22.621Z","repository":{"id":195075855,"uuid":"673422692","full_name":"denoland/docs","owner":"denoland","description":"Deno documentation, examples and API Reference. Powered by Lume.","archived":false,"fork":false,"pushed_at":"2025-10-01T15:19:38.000Z","size":54255,"stargazers_count":165,"open_issues_count":198,"forks_count":324,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-10-02T04:47:09.159Z","etag":null,"topics":["deno","hacktoberfest"],"latest_commit_sha":null,"homepage":"https://docs.deno.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/denoland.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-08-01T15:30:40.000Z","updated_at":"2025-10-01T15:01:02.000Z","dependencies_parsed_at":"2023-09-29T21:03:15.862Z","dependency_job_id":"ed1675bb-eff0-40bb-977f-f9df1e59e20d","html_url":"https://github.com/denoland/docs","commit_stats":{"total_commits":1383,"total_committers":439,"mean_commits":3.150341685649203,"dds":0.9262472885032538,"last_synced_commit":"c5a9af7dd89693c3f6f00aff6181ffcecc9121d4"},"previous_names":["denoland/deno-docs","denoland/docs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/denoland/docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoland%2Fdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoland%2Fdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoland%2Fdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoland%2Fdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/denoland","download_url":"https://codeload.github.com/denoland/docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoland%2Fdocs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278273803,"owners_count":25959801,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deno","hacktoberfest"],"created_at":"2024-09-24T20:52:29.104Z","updated_at":"2025-10-04T06:19:22.615Z","avatar_url":"https://github.com/denoland.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Deno Docs\n\nThis repository contains the website running\n[docs.deno.com](https://docs.deno.com). The intent of this project is to\ncentralize all official Deno documentation content in a single website. The Deno\nDocs site is built using [Lume](https://lume.land/), an extremely fast static\nsite generator.\n\nThe `docs.deno.com` website is hosted on [Deno Deploy](https://deno.com/deploy).\n\n## Local development\n\nInstall [Deno](https://deno.com).\n\nYou can then start the local development server with:\n\n```console\ndeno task serve\n```\n\nThis will launch a browser window open to\n[localhost:3000](http://localhost:3000), where you will see any doc content\nchanges you make update live. Here redirects will not work. If you want\nredirects to work, you need to run:\n\n```console\ndeno task build\ndeno task prod\n```\n\nWhich will start a Deno server on [localhost:8000](http://localhost:8000) used\nin production, which handles redirects.\n\nthe above commands will defauilt to performing as complete build of the site\nincluding all of the more expensive operations. You can also perform a lighter\nbuild by running:\n\n```console\ndeno task build:light\n```\n\nThis will build the site without generating the Open Graph images and other more\ntime-consuming operations which might be desirable to skip during local\ndevelopement work.\n\n## Developing styles and components\n\nWe are increasingly making use of global components to improve consistency and\nreduce duplication. A styleguide has been created to preview and develop these\ncomponents and is generated during the build process.\n\nYou can browse to it in the site at `/styleguide/`\n\nTo avoid longer build times of the entire site and all of its content while\ndeveloping UI elements and components, a styleguide-only build is avaiable which\nperforms the initial global configureation for the site, but then only generates\nand watches for changes in the `/styleguide` folder of the repo.\n\nTo work on just the components and UI elements and review them within\nstyleguide, run:\n\n```console\ndeno task serve:style\n```\n\nThen browse to the styleguide section of the site at `/styleguide/`\n\n## Link checking\n\nTo ensure all links in the documentation work correctly, you can run the link\nchecker locally before committing changes. This helps catch broken links early\nin the development process.\n\n### Running link checker locally\n\nThe link checker needs to run against a live server. Here's the workflow:\n\n1. **Start the dev server** (in one terminal):\n\n   ```console\n   deno task dev\n   ```\n\n   Wait for it to fully start (may take 30-60 seconds on first run).\n\n2. **Run the link checker** (in another terminal):\n\n   ```console\n   deno task check:links:local\n   ```\n\nThis will check all links on your local site and report any issues.\n\n### Pre-commit hook (optional)\n\nFor automatic link checking before commits, you can install a pre-commit hook:\n\n```console\ndeno task install:hooks\n```\n\nThis will check links automatically whenever you commit markdown files. You can\nbypass it temporarily with:\n\n```console\ngit commit --no-verify\n```\n\n**Note for Windows users**: If you're using Git Bash or WSL, the pre-commit hook\nshould work normally. If you encounter issues, you can manually run\n`deno task check:links:local` before committing.\n\nThe link checker also runs automatically in CI for all deployments.\n\n## Editing content\n\nThe actual content of the docs site is found mostly in these folders:\n\n- `runtime` - docs for the Deno CLI / runtime\n- `deploy` - docs for the Deno Deploy cloud service\n- `subhosting` - docs for Deno Subhosting\n- `examples` - docs for the [Examples](#Examples) section\n\nMost files are [markdown](https://lume.land/plugins/markdown/), but even\nmarkdown files are processed with [MDX](https://mdxjs.com/), which enables you\nto use JSX syntax within your markdown files.\n\nLeft navigation for the different doc sections are configured in the `_data.ts`\nfiles in their respective content directories.\n\n- `runtime/_data.ts` - sidebar config for the Runtime section\n- `deploy/_data.ts` - sidebar config for the Deno Deploy section\n\nStatic files (like screenshots) can be included directly in the `runtime`,\n`deploy`, or `kv` folders, and referenced by relative URLs in your markdown.\n\n## Reference docs\n\nThe reference docs served at `/api` are generated via the `deno doc` subcommand.\nTo generate the reference docs locally, run:\n\n```console\ndeno task reference\n```\n\nThis will generate the reference docs, and you can use the `serve` or `build`\ntasks.\n\nThe API reference documentation is generated from type definitions in the\n[Deno source code](https://github.com/denoland/deno). The API reference content\ncan be edited by modifying the JSDoc comments in the corresponding `d.ts` files\nin the Deno source code. Once merged, the changes will be reflected in the API\nreference documentation when the Deno documentation site is next updated.\n\n### Previewing API reference changes\n\nIn order to preview changes to the API reference, take the following steps:\n\n1. Make changes to the JSDoc comments in the Deno source code\n1. [Build the Deno CLI locally](https://docs.deno.com/runtime/contributing/building_from_source/),\n   including your JSDoc changes\n1. For convenience, create an alias of `d_deno` to point to your local build of\n   the Deno CLI (typically in the `target/debug/deno` directory of your CLI\n   repo)\n1. Generate the reference docs from your local build of the Deno CLI by running\n   in the root directory `d_deno task reference`\n1. Run the `deno task serve` command in the root directory to see the changes\n\n## Versioning docs content\n\nPhilosophically, we want to maintain as few discrete versions of the\ndocumentation as possible. This will reduce confusion for users (reduce the\nnumber of versions they need to think about), improve search indexing, and help\nus maintain the docs by keeping our build times faster.\n\nIn general, we should only version the documentation **when we want to\nconcurrently maintain several versions of the docs**, like for major/LTS\nversions. For example - the [Node.js docs](https://nodejs.org/en/docs) are only\nversioned for major releases, like `20.x` and `19.x`. We will adopt this pattern\nas well, and won't have versioned docs for patch or feature releases.\n\nFor additive changes, it should usually be sufficient to indicate which version\na feature or API was released in. For example - in the Node 20 docs, the\n[register function](https://nodejs.org/dist/latest-v20.x/docs/api/module.html#moduleregister)\nis marked as being added in version `20.6.0`.\n\n## Caching of the API Reference docs\n\nThe generation of the API reference docs is a very time-consuming operation. To\nspeed up this process, we use a caching system that tracks file changes and only\nregenerates documentation when necessary.\n\n### How the caching system works\n\nThe caching system uses multiple cache files in the `reference_gen/` directory:\n\n- **`.gen-cache.json`** - Main cache tracking file modification times and\n  content hashes for source files\n- **`.gen-cache-modules.json`** - Module-specific cache for individual\n  TypeScript definition files\n- **`.node-incremental-cache.json`** - Incremental cache for Node.js API\n  documentation\n\nThe cache system performs content-based hashing to detect actual changes (not\njust timestamp changes) and supports both file-level and directory-level\ntracking. It automatically invalidates and rebuilds cache entries when:\n\n- Source `.d.ts` files are modified\n- File content hashes change\n- Dependencies are updated\n\nIf you need to force a complete regeneration (bypassing the cache), you can\ndelete the cache files:\n\n```console\ndeno task cache:clear\n```\n\n## Contribution\n\nWe are very grateful for any help you can offer to improve Deno's documentation!\nFor any small copy changes or fixes, please feel free to\n[submit a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)\ndirectly to the `main` branch of this repository.\n\nFor larger changes, please\n[create a GitHub issue first](https://github.com/denoland/deno-docs/issues) to\ndescribe your proposed updates. It will be better to get feedback on your\nconcept first before going to the trouble of writing a large number of docs!\n\nOver time, we will add more in the way of linting and formatting to the pull\nrequest process. But for now, you should merely ensure that `npm run build`\nsucceeds without error before submitting a pull request. This will ensure that\nthere are no broken links or invalid MDX syntax in the content you have\nauthored.\n\n## Examples\n\n[Deno by Example](https://docs.deno.com/examples) is a collection of small\nsnippets of code, tutorials and videos showcasing various functions of the APIs\nimplemented in Deno.\n\n### Adding an example script\n\n- Examples are written in TypeScript\n- Each example should be a single file, no more than 50 lines\n- Each example should be a self-contained unit, and should depend on no\n  dependencies other than Deno builtins and the standard library, unless a\n  third-party library is strictly required.\n- Each example should be runnable without additional dependencies on all systems\n  (exceptions can be made for platform specific functionality)\n- Examples should be introduce at most one (or in exceptional cases two or\n  three) concepts in Deno / Web APIs. Existing concepts should be linked to.\n- Code should be kept _really simple_, and should be easy to read and understand\n  by anyone. Do not use complicated code constructs, or hard to follow builtins\n  like `Array.reduce`\n- Concepts introduced in an example should be explained\n\n### Adding an example\n\nTo add an example, create a file in the `examples/scripts` directory. The file\nname should be a short description of the example (in kebab case) and the\ncontents should be the code for the example. The file should be in the `.ts`\nformat. The file should start with a JSDoc style multi line comment that\ndescribes the example:\n\n```ts\n/**\n * @title HTTP server: Hello World\n * @difficulty intermediate\n * @tags cli, deploy\n * @run --allow-net \u003curl\u003e\n * @group Basics\n *\n * An example of a HTTP server that serves a \"Hello World\" message.\n */\n```\n\nYou should add a title, a difficulty level (`beginner` or `intermediate`), and a\nlist of tags (`cli`, `deploy`, `web` depending on where an example is runnable).\nThe `@run` tag should be included if the example can be run locally by just\ndoing `deno run \u003curl\u003e`. If running requires permissions, add these:\n\n```ts\n/**\n * ...\n * @run --allow-net --allow-read \u003curl\u003e\n */\n```\n\nAfter the pragmas, you can add a description of the example. This is optional,\nbut recommended for most examples. It should not be longer than one or two\nlines. The description shows up at the top of the example in the example page,\nand in search results.\n\nAfter the JS Doc comment, you can write the code. Code can be prefixed with a\ncomment that describes the code. The comment will be rendered next to the code\nin the example page.\n\n## Special thanks for historical contributions\n\nThis repository was created using content from the\n[Deno Manual](https://github.com/denoland/manual), a project contributed to by\nhundreds of developers since 2018. You can view a list of historical\ncontributors to the Deno documentation in this repository and the manual with\nthis command:\n\n```bash\ngit shortlog -s -n\n```\n\n## Orama Search Configuration\n\n1. **Sign up for Orama Cloud**: Go to\n   [https://cloud.oramasearch.com/](https://cloud.oramasearch.com/) and create\n   an account.\n\n2. **Create a new index**:\n   - In the Orama dashboard, create a new index\n   - Set the data source to docs.deno.com or upload the documentation content\n     directly\n\n3. **Get your credentials**:\n   - In your Orama dashboard, you'll find your **Endpoint URL** and **Public API\n     Key**\n   - These are safe to include in frontend applications\n\n4. **Configure the search**:\n   - Open `search.client.ts`\n   - Replace `YOUR_ORAMA_ENDPOINT` with your actual endpoint URL\n   - Replace `YOUR_ORAMA_API_KEY` with your actual public API key\n\n### Data Sources\n\nFor the Deno docs, we have several options:\n\n#### Option 1: Web Crawler (Recommended)\n\n- Use Orama's built-in web crawler to index your documentation site\n- Go to Data Sources → Web Crawler in your Orama dashboard\n- Add your site URL (e.g., `https://docs.deno.com`)\n- Configure crawling rules if needed\n\n#### Option 2: Static Files\n\n- Export your documentation content as JSON\n- Upload it directly to Orama\n- This gives you more control over what gets indexed\n\n#### Option 3: API Integration\n\n- Use Orama's REST API to programmatically add/update content\n- Useful to integrate with our build process\n\n### Configuration Example\n\nIn `search.client.ts`, update the ORAMA_CONFIG object:\n\n```typescript\nconst ORAMA_CONFIG = {\n  endpoint: \"https://cloud.orama.com/v1/indexes/your-index-id\",\n  apiKey: \"your-public-api-key-here\",\n};\n```\n\n### Customization\n\nWe can customize the search experience by modifying:\n\n- **Search modes**: Change between \"fulltext\", \"vector\", or \"hybrid\" search\n- **Result limit**: Adjust how many results to show\n- **UI styling**: Modify the CSS classes in the search components\n- **Result formatting**: Change how search results are displayed\n\n## Deployment\n\nThe `docs.deno.com` site is updated with every push to the `main` branch, which\nshould be done via pull request to this repository.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenoland%2Fdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdenoland%2Fdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenoland%2Fdocs/lists"}