Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: remove upstreamed ddoc stylings and update README #571

Merged
merged 3 commits into from
Jul 11, 2024
Merged

fix: remove upstreamed ddoc stylings and update README #571

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d605caa
chore: upstream ddoc stylings
crowlKats Jul 11, 2024
8010a7c
update README.md
crowlKats Jul 11, 2024
226701d
update README.md
crowlKats Jul 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 27 additions & 95 deletions README.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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;
}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The styles here that adjust the ToC position are still necessary because if all of ddoc is in a grid it doesn't anchor the navigation content to the left with a fixed width so I think ddoc should be a flex where the categories list is on the left and the rest of the content takes up the rest of the space.

We could either keep that in here until the next deno_doc pass or migrate it to styles.css as something that is a deno-docs specific interpretation

Screenshot 2024-07-11 at 9 05 39 AM


.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;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some of these long document navigation styles should move or else we lose the formatting of the document navigation

Screenshot 2024-07-11 at 9 51 30 AM Screenshot 2024-07-11 at 9 49 19 AM

}

.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
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,9 +207,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;
}
}