README.md
This repository contains the website running docs.deno.com. The intent of this project is to centralize all official Deno documentation content in a single website. The Deno Docs site is built using Lume, an extremely fast static site generator.
The docs.deno.com website is hosted on Deno Deploy.
Install Deno.
You can then start the local development server with:
deno task serve
This will launch a browser window open to localhost:3000, where you will see any doc content changes you make update live. Here redirects will not work. If you want redirects to work, you need to run:
deno task build
deno task prod
Which will start a Deno server on localhost:8000 used in production, which handles redirects.
the above commands will defauilt to performing as complete build of the site including all of the more expensive operations. You can also perform a lighter build by running:
deno task build:light
This will build the site without generating the Open Graph images and other more time-consuming operations which might be desirable to skip during local developement work.
We are increasingly making use of global components to improve consistency and reduce duplication. A styleguide has been created to preview and develop these components and is generated during the build process.
You can browse to it in the site at /styleguide/
To avoid longer build times of the entire site and all of its content while
developing UI elements and components, a styleguide-only build is avaiable which
performs the initial global configureation for the site, but then only generates
and watches for changes in the /styleguide folder of the repo.
To work on just the components and UI elements and review them within styleguide, run:
deno task serve:style
Then browse to the styleguide section of the site at /styleguide/
To ensure all links in the documentation work correctly, you can run the link checker locally before committing changes. This helps catch broken links early in the development process.
The link checker needs to run against a live server. Here's the workflow:
Start the dev server (in one terminal):
deno task dev
Wait for it to fully start (may take 30-60 seconds on first run).
Run the link checker (in another terminal):
deno task check:links:local
This will check all links on your local site and report any issues.
For automatic link checking before commits, you can install a pre-commit hook:
deno task install:hooks
This will check links automatically whenever you commit markdown files. You can bypass it temporarily with:
git commit --no-verify
Note for Windows users: If you're using Git Bash or WSL, the pre-commit hook
should work normally. If you encounter issues, you can manually run
deno task check:links:local before committing.
The link checker also runs automatically in CI for all deployments.
The actual content of the docs site is found mostly in these folders:
runtime - docs for the Deno CLI / runtimedeploy - docs for the Deno Deploy cloud servicesubhosting - docs for Deno Subhostingexamples - docs for the Examples sectionMost files are markdown, but even markdown files are processed with MDX, which enables you to use JSX syntax within your markdown files.
Left navigation for the different doc sections are configured in the _data.ts
files in their respective content directories.
runtime/_data.ts - sidebar config for the Runtime sectiondeploy/_data.ts - sidebar config for the Deno Deploy sectionStatic files (like screenshots) can be included directly in the runtime,
deploy, or kv folders, and referenced by relative URLs in your markdown.
The reference docs served at /api are generated via the deno doc subcommand.
To generate the reference docs locally, run:
deno task reference
This will generate the reference docs, and you can use the serve or build
tasks.
The API reference documentation is generated from type definitions in the
Deno source code. The API reference content
can be edited by modifying the JSDoc comments in the corresponding d.ts files
in the Deno source code. Once merged, the changes will be reflected in the API
reference documentation when the Deno documentation site is next updated.
In order to preview changes to the API reference, take the following steps:
d_deno to point to your local build of
the Deno CLI (typically in the target/debug/deno directory of your CLI
repo)d_deno task referencedeno task serve command in the root directory to see the changesPhilosophically, we want to maintain as few discrete versions of the documentation as possible. This will reduce confusion for users (reduce the number of versions they need to think about), improve search indexing, and help us maintain the docs by keeping our build times faster.
In general, we should only version the documentation when we want to
concurrently maintain several versions of the docs, like for major versions.
For example - the Node.js docs are only versioned
for major releases, like 20.x and 19.x. We will adopt this pattern as well,
and won't have versioned docs for patch or feature releases.
For additive changes, it should usually be sufficient to indicate which version
a feature or API was released in. For example - in the Node 20 docs, the
register function
is marked as being added in version 20.6.0.
The generation of the API reference docs is a very time-consuming operation. To speed up this process, we use a caching system that tracks file changes and only regenerates documentation when necessary.
The caching system uses multiple cache files in the reference_gen/ directory:
.gen-cache.json - Main cache tracking file modification times and
content hashes for source files.gen-cache-modules.json - Module-specific cache for individual
TypeScript definition files.node-incremental-cache.json - Incremental cache for Node.js API
documentationThe cache system performs content-based hashing to detect actual changes (not just timestamp changes) and supports both file-level and directory-level tracking. It automatically invalidates and rebuilds cache entries when:
.d.ts files are modifiedIf you need to force a complete regeneration (bypassing the cache), you can delete the cache files:
deno task cache:clear
We are very grateful for any help you can offer to improve Deno's documentation!
For any small copy changes or fixes, please feel free to
submit a pull request
directly to the main branch of this repository.
For larger changes, please create a GitHub issue first to describe your proposed updates. It will be better to get feedback on your concept first before going to the trouble of writing a large number of docs!
Over time, we will add more in the way of linting and formatting to the pull
request process. But for now, you should merely ensure that npm run build
succeeds without error before submitting a pull request. This will ensure that
there are no broken links or invalid MDX syntax in the content you have
authored.
Deno by Example is a collection of small snippets of code, tutorials and videos showcasing various functions of the APIs implemented in Deno.
Array.reduceTo add an example, create a file in the examples/scripts directory. The file
name should be a short description of the example (in kebab case) and the
contents should be the code for the example. The file should be in the .ts
format. The file should start with a JSDoc style multi line comment that
describes the example:
/**
* @title HTTP server: Hello World
* @difficulty intermediate
* @tags cli, deploy
* @run --allow-net <url>
* @group Basics
*
* An example of a HTTP server that serves a "Hello World" message.
*/
You should add a title, a difficulty level (beginner or intermediate), and a
list of tags (cli, deploy, web depending on where an example is runnable).
The @run tag should be included if the example can be run locally by just
doing deno run <url>. If running requires permissions, add these:
/**
* ...
* @run --allow-net --allow-read <url>
*/
After the pragmas, you can add a description of the example. This is optional, but recommended for most examples. It should not be longer than one or two lines. The description shows up at the top of the example in the example page, and in search results.
After the JS Doc comment, you can write the code. Code can be prefixed with a comment that describes the code. The comment will be rendered next to the code in the example page.
This repository was created using content from the Deno Manual, a project contributed to by hundreds of developers since 2018. You can view a list of historical contributors to the Deno documentation in this repository and the manual with this command:
git shortlog -s -n
Sign up for Orama Cloud: Go to https://cloud.oramasearch.com/ and create an account.
Create a new index:
Get your credentials:
Configure the search:
search.client.tsYOUR_ORAMA_ENDPOINT with your actual endpoint URLYOUR_ORAMA_API_KEY with your actual public API keyFor the Deno docs, we have several options:
https://docs.deno.com)In search.client.ts, update the ORAMA_CONFIG object:
const ORAMA_CONFIG = {
endpoint: "https://cloud.orama.com/v1/indexes/your-index-id",
apiKey: "your-public-api-key-here",
};
We can customize the search experience by modifying:
The docs.deno.com site is updated with every push to the main branch, which
should be done via pull request to this repository.
MIT