Skip to content

Commit

Permalink
update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
crowlKats committed Jul 11, 2024
1 parent d605caa commit 8010a7c
Show file tree
Hide file tree
Showing 2 changed files with 20 additions and 96 deletions.
113 changes: 18 additions & 95 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,67 +2,42 @@

This repository contains the website running
[docs.deno.com](https://docs.deno.com). The intent of this project is to
eventually centralize all official Deno documentation content in a single
website. The Deno Docs site is built using
[Docusaurus 2](https://docusaurus.io/), a static site generator optimized for
documentation websites.
centralize all official Deno documentation content in a single website. The Deno
Docs site is built using [Lume](https://lume.land/), an extremely fast static
site generator.

The `docs.deno.com` website is hosted on [Deno Deploy](https://deno.com/deploy),
where it is fronted by a [Hono](https://hono.dev/) web server that handles
redirects and other dynamic content requests as they become necessary.
The `docs.deno.com` website is hosted on [Deno Deploy](https://deno.com/deploy).

## Local development

Install [Deno](https://deno.com) and your favorite package manager (eg: `npm`)

```console
npm install
```
Install [Deno](https://deno.com).

You can then start the local development server with:

```console
DENO_FUTURE=1 deno task start
deno task serve
```

This will launch a browser window open to
[localhost:3000](http://localhost:3000), where you will see any doc content
changes you make update live.

To test the generated static site in a production configuration, run:

```console
DENO_FUTURE=1 deno task build
```

This will generate a static site to the `build` folder locally. To test the
production server (through the actual Deno / Hono server), run this command:
changes you make update live. Here redirects will not work. If you want
redirects to work, you need to run:

```console
DENO_FUTURE=1 deno task serve
deno task build
deno task prod
```

This will start a Deno server on [localhost:8000](http://localhost:8000), where
you can preview the site as it will run on Deno Deploy.

Sometimes, after making a Docusaurus config change, you will run into an error
and need to clean Docusaurus' generated assets. You can do this by running:

```console
DENO_FUTURE=1 deno task clear
```

This will solve most errors you encounter while refactoring the site. Static
assets will be rebuilt from scratch the next time you run `build` or `start`
scripts.
Which will start a Deno server on [localhost:8000](http://localhost:8000) used
in production, which handles redirects.

## Editing content

The actual content of the docs site is found mostly in these three folders:
The actual content of the docs site is found mostly in these folders:

- `runtime` - docs for the Deno CLI / runtime
- `deploy` - docs for the Deno Deploy cloud service
- `kv` - docs for Deno KV, Deno's integrated database
- `subhosting` - docs for Deno Subhosting

Most files are [markdown](https://docusaurus.io/docs/markdown-features), but
even markdown files are processed with [MDX](https://mdxjs.com/), which enables
Expand Down Expand Up @@ -122,62 +97,6 @@ it.
import { copy } from "https://deno.land/std@$STD_VERSION/fs/copy.ts";
```

To include version number in markdown / MDX content, we recommend using the
`<Replacement />` component:

```mdx
import Replacement from "@site/src/components/Replacement";

The current CLI version is **<Replacement for="CLI_VERSION"/>**.
```

If you are writing inline JSX, you can also use the replacements object directly
like so:

```mdx
import { replacements } from "@site/src/components/Replacement";

<p>
The current CLI version is <code>{ replacements.CLI_VERSION }</code>.
</p>
```

## Server-side code and redirects

The Deno code that serves the site in production is in the `src-deno` folder.
When the `npm run build` command is executed for a production Docusaurus build,
it also copies the contents of the `src-deno` folder (unchanged) into the
resulting `build` folder, which will be our project root for Deno Deploy.

Right now, there is just a very thin [Hono](https://hono.dev/) server sitting on
top of the static assets generated by Docusaurus. The only interesting job the
Hono app has right now is handling redirects, of which there are several from
the previous Deno doc sites.

To add a redirect, open `src-deno/redirects.ts` and configure a new route in the
default exported function. The default status code of `301` should be sufficient
for most cases.

## New release process for Deno runtime

Let's say that a new minor release is ready for Deno, with CLI version `1.99`
and standard library version `0.999.0`. Here's how I would recommend approaching
the docs for this release right now.

- Create a feature branch for the release, like `release_1_99` or similar
- Update `replacements.json` with the upcoming CLI and standard lib versions
- As the release is developed, add docs changes to this branch
- When the release is ready, submit a PR to the `main` branch from this feature
branch
- When the branch is merged, create a `v1.99` tag from the new `main` branch

For patch releases, I would recommend simply submitting pull requests to the
`main` branch with relevant updates to `replacements.json` as required.

If we decide we'd like to have "canary" docs for upcoming versions, we can
discuss how to make that possible with
[Docusaurus versions](https://docusaurus.io/docs/versioning).

## Contribution

We are very grateful for any help you can offer to improve Deno's documentation!
Expand Down Expand Up @@ -256,6 +175,10 @@ 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.

## Reference docs

The reference docs are generated via the `deno doc` sub

## Special thanks for historical contributions

This repository was created using content from the
Expand Down
3 changes: 2 additions & 1 deletion deno.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@
"tasks": {
"lume": "echo \"import 'lume/cli.ts'\" | deno run -A -",
"build": "deno task lume",
"serve": "deno task lume -s"
"serve": "deno task lume -s",
"prod": "cd _site && deno run --allow-read=. --allow-net server.ts"
},
"compilerOptions": {
"types": [
Expand Down

0 comments on commit 8010a7c

Please sign in to comment.