Skip to content

Commit

Permalink
fix: remove upstreamed ddoc stylings and update README (denoland#571)
Browse files Browse the repository at this point in the history
  • Loading branch information
@crowlKats
crowlKats authored Jul 11, 2024
1 parent c0fe01c commit 8704014
Show file tree
Hide file tree
Showing 4 changed files with 85 additions and 240 deletions.
122 changes: 27 additions & 95 deletions README.md
View file
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:

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

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:
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 clear
deno task build
deno task prod
```

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,19 @@ 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` subcommand. To generate the
reference docs locally, in the `reference_gen` directory, run:

```console
deno task types
deno task doc
```

This will generate the reference docs, and you can use the `serve` or `build`
tasks.

## Special thanks for historical contributions

This repository was created using content from the
Expand Down
3 changes: 2 additions & 1 deletion deno.json
View file
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
140 changes: 0 additions & 140 deletions overrides.css
View file
Original file line number Diff line number Diff line change
@@ -1,149 +1,9 @@
/* Deno Doc Overrides */

div.ddoc {
@apply flex h-screen p-4 pt-2 lg:p-2 lg:pt-0;
}

/* First column: fixed width of 290px */
.ddoc > :first-child {
@apply w-[290px] flex-shrink-0;
}

/* Second column: takes up the remaining space */
.ddoc > :nth-child(2) {
@apply flex-grow;
}

.toc {
@apply hidden;
}

.ddoc > .toc {
@apply hidden md:flex md:flex-col !important;
}

.ddoc > div > div#content > div.toc {
@apply hidden xl:flex xl:flex-col !important;
}

.ddoc > .toc {
@apply h-full max-h-screen border-r border-gray-000;
}

.ddoc .documentNavigation > h3 {
margin: 0.75rem 0.75rem 0.5rem !important;
padding-bottom: 0.1rem;
@apply text-gray-4 font-normal text-xs border-b border-gray-000 leading-normal uppercase !important;
}

.ddoc .documentNavigation > ul {
@apply flex-grow overflow-y-auto;
}

.ddoc .documentNavigation > ul > li {
@apply mt-0.5 mx-3;
}

.ddoc .documentNavigation > ul > li > a {
@apply text-gray-3 text-sm py-1.5 px-3.5 hover:bg-blue-50 rounded-lg hover:no-underline !important;
}

.ddoc > div:not(.toc) {
@apply flex flex-col;
}

#content {
@apply mt-4 flex flex-row justify-between !important;
}

#content > main {
@apply pb-0 flex flex-col gap-3 flex-grow !important;
}

#content > .toc {
@apply flex-shrink-0 min-w-[250px] max-w-[300px] !important;
}

#content > main > section + div {
@apply max-w-[75ch] !important;
}

.ddoc .markdown {
@apply max-w-[40ch] sm:max-w-screen-sm md:max-w-screen-md lg:max-w-[75ch] !important;
}

/* This comes from gfm css, should be replaced with something in our color palette once we establish it. */
.ddoc .markdown :not(pre) > code {
background-color: var(--color-neutral-muted) !important;
}

.ddoc .markdown pre {
@apply border-gray-000 !important;
}

.ddoc .max-w-prose {
@apply max-w-[75ch] !important;
}

.ddoc > div > div#content > div.toc > div > nav.documentNavigation > h3 {
@apply hidden !important;
}

.ddoc > div > div#content > div.toc > div > nav.documentNavigation > ul {
@apply border-l border-gray-000 text-gray-1 text-[.8rem] leading-none !important;
}

.ddoc
> div
> div#content
> div.toc
> div
> nav.documentNavigation
> ul
> li:has(> a) {
@apply pb-0 !important;
}

.ddoc nav.documentNavigation li:has(> ul) {
@apply mt-0 !important;
/* CSS styles here */
}

.ddoc
> div
> div#content
> div.toc
> div
> nav.documentNavigation
> ul
> li
> ul
> li {
@apply mt-1 !important;
}

.ddoc
> div
> div#content
> div.toc
> div
> nav.documentNavigation
> ul
> li
> ul
> li
> a {
@apply hover:bg-blue-50 rounded-lg hover:no-underline p-1 !important;
}

@media (min-width: 1024px) {
.ddoc:not(:has(> div.toc)),
.ddoc:has(> div.toc) > div:not(.toc) {
padding-top: 0.25rem !important;
padding-left: 0.5rem !important;
}
}

.ddoc .usageContent {
@apply bg-primary/5 border-primary/25 pt-3.5 pb-4 !important;
}
Expand Down
60 changes: 56 additions & 4 deletions styles.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -219,9 +219,61 @@ body:not(:has(.ddoc)) {
}

/* Custom DDOC styles for the Deno documentation */
.ddoc {
/* Categories panel */
> .toc {
@apply border-r border-gray-000;

.documentNavigation {
> h3 {
margin: 0.75rem 0.75rem 0.5rem !important;
padding-bottom: 0.1rem;
@apply text-gray-4 font-normal text-xs border-b border-gray-000 leading-normal uppercase !important;
}
}
}

.documentNavigation > ul > li > a {
@apply text-gray-3 hover:bg-blue-50 rounded-lg hover:no-underline py-1.5 px-3.5 !important
}

.contextLink {
@apply text-primary !important;
/* 40% opacity of for decoration color primary */
text-decoration-color: rgba(9, 107, 218, 0.4) !important;
}

#content .toc .documentNavigation {
> h3 {
@apply hidden !important;
}

> ul {
@apply border-l border-gray-000 !important;

> ul > li a {
@apply hover:bg-blue-50 rounded-lg hover:no-underline !important;
}
}
}

.markdown {
pre {
@apply border-gray-000 !important;
}

/* This comes from gfm css, should be replaced with something in our color palette once we establish it. */
:not(pre) > code {
background-color: var(--color-neutral-muted) !important;
}
}
}

.ddoc .contextLink {
@apply text-primary !important;
/* 40% opacity of for decoration color primary */
text-decoration-color: rgba(9, 107, 218, 0.4) !important;
@media (min-width: 1024px) {
/* no category panel, category panel but no document navigation */
.ddoc:not(:has(> div.toc)),
.ddoc:has(> div.toc) > div:not(.toc) {
padding-top: 0.25rem !important;
padding-left: 0.5rem !important;
}
}

0 comments on commit 8704014

Please sign in to comment.