Skip to content

Commit

Permalink
docs: flatten navigation structure and rework content pages (#746)
Browse files Browse the repository at this point in the history 
Co-authored-by: Marvin Hagemeister <marvin@deno.com>
  • Loading branch information
@thisisjofrank @marvinhagemeister
thisisjofrank and marvinhagemeister authored Aug 28, 2024
1 parent f491fdf commit 26e8f40
Show file tree
Hide file tree
Showing 52 changed files with 2,275 additions and 3,792 deletions.
2 changes: 1 addition & 1 deletion _components/Header.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ export default function Header({
<HeaderItem
url={url}
activeOn="/runtime"
href="/runtime/manual"
href="/runtime/"
name="Runtime Manual"
hideOnMobile
/>
Expand Down
2 changes: 2 additions & 0 deletions _config.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,8 @@ site.copy("deploy/kv/manual/images");
site.copy("deploy/tutorials/images");
site.copy("deploy/kv/tutorials/images");
site.copy("runtime/manual/images");
site.copy("runtime/fundamentals/images");
site.copy("runtime/getting_started/images");
site.copy("deploy/manual/images");
site.copy("deno.json");
site.copy("go.json");
Expand Down
1,047 changes: 164 additions & 883 deletions deno.lock
View file

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion deploy/tutorials/simple-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,7 @@ the `localhost` URL with your live production URL on Deno Deploy:
```shell
curl --header "Content-Type: application/json" \
--request POST \
--data '{"url":"https://docs.deno.com/runtime/manual","slug":"denodocs"}' \
--data '{"url":"https://docs.deno.com/runtime/","slug":"denodocs"}' \
https://your-deno-project-url-here.deno.dev/
```

Expand Down
2 changes: 1 addition & 1 deletion examples.page.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ export const sidebar = [
items: [
{
label: "Runtime Manual",
id: "/runtime/manual/",
id: "/runtime/",
},
{
label: "Examples",
Expand Down
26 changes: 13 additions & 13 deletions go.json
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
{
"permissions": "/runtime/manual/basics/permissions/",
"config": "/runtime/manual/getting_started/configuration_file/",
"ide": "/runtime/manual/getting_started/setup_your_environment/#using-an-editor%2Fide",
"--allow-env": "/runtime/manual/basics/permissions/#environment-access",
"--allow-ffi": "/runtime/manual/basics/permissions/#ffi-(foreign-function-interface)",
"--allow-hrtime": "/runtime/manual/basics/permissions/#high-resolution-time",
"--allow-net": "/runtime/manual/basics/permissions/#network-access",
"--allow-read": "/runtime/manual/basics/permissions/#file-system-read-access",
"--allow-run": "/runtime/manual/basics/permissions/#running-subprocesses",
"--allow-sys": "/runtime/manual/basics/permissions/#system-information",
"--allow-write": "/runtime/manual/basics/permissions/#file-system-write-access",
"--allow-all": "/runtime/manual/basics/permissions/#all-permissions",
"--unsafely-ignore-certificate-errors": "/runtime/manual/basics/permissions/#certification-errors"
"permissions": "/runtime/fundamentals/security/",
"config": "/runtime/fundamentals/configuration/",
"ide": "/runtime/getting_started/setup_your_environment/#setting-up-your-editor%2Fide",
"--allow-env": "/runtime/fundamentals/security/#environment-access",
"--allow-ffi": "/runtime/fundamentals/security/#ffi-(foreign-function-interface)",
"--allow-hrtime": "/runtime/fundamentals/security/#high-resolution-time",
"--allow-net": "/runtime/fundamentals/security/#network-access",
"--allow-read": "/runtime/fundamentals/security/#file-system-read-access",
"--allow-run": "/runtime/fundamentals/security/#running-subprocesses",
"--allow-sys": "/runtime/fundamentals/security/#system-information",
"--allow-write": "/runtime/fundamentals/security/#file-system-write-access",
"--allow-all": "/runtime/fundamentals/security/#all-permissions",
"--unsafely-ignore-certificate-errors": "/runtime/fundamentals/security/#certification-errors"
}
14 changes: 7 additions & 7 deletions index.page.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ export const sidebar = [
items: [
{
label: "Runtime Manual",
id: "/runtime/manual/",
id: "/runtime/",
},
{
label: "Examples",
Expand Down Expand Up @@ -57,7 +57,7 @@ export default function () {
<div class="flex flex-row gap-4 mt-8">
<DocsCTA
text="Get Started"
href="/runtime/manual"
href="/runtime/"
product="runtime"
/>
<DocsCTA
Expand Down Expand Up @@ -97,15 +97,15 @@ export default function () {
title="Deno basics"
description="New to Deno? This is the place to start."
linktext="Get started"
link="/runtime/manual/getting_started/first_steps"
link="/runtime/"
product="runtime"
/>

<ContentItem
title="Configuration"
description="Customizations for Deno’s built-in TypeScript compiler, formatter, and linter."
linktext="Deno config"
link="/runtime/manual/getting_started/configuration_file"
link="/runtime/fundamentals/configuration"
product="runtime"
/>

Expand Down Expand Up @@ -399,23 +399,23 @@ export default function () {
title="Quick Start"
description="Configure your subhosting account and you'll be hosting customer code in minutes."
linktext="Quick start"
link="/runtime/manual/getting_started/first_steps"
link="/subhosting/manual/quick_start/"
product="deploy"
/>

<ContentItem
title="Subhosting architecture"
description="Learn how subhosting works with our platform architecture guides."
linktext="Learn about subhosting"
link="/runtime/manual/getting_started/configuration_file"
link="/runtime/fundamentals/configuration"
product="deploy"
/>

<ContentItem
title="REST API"
description="Quickly provision new projects and make deployments through our REST API."
linktext="REST API"
link="/runtime/manual/basics/testing/"
link="/subhosting/manual/#rest-api-reference-and-openapi-spec"
product="deploy"
/>
</div>
Expand Down
64 changes: 22 additions & 42 deletions runtime/_data.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,32 +5,19 @@ export const sidebar = [
title: "Getting Started",
items: [
{
label: "Quick Start",
id: "/runtime/manual/",
},
{
label: "Deno Basics",
items: [
"/runtime/manual/getting_started/first_steps/",
"/runtime/manual/getting_started/setup_your_environment/",
"/runtime/manual/getting_started/command_line_interface/",
"/runtime/manual/getting_started/configuration_file/",
"/runtime/manual/getting_started/web_frameworks/",
"/runtime/manual/basics/permissions/",
"/runtime/manual/basics/standard_library/",
"/runtime/manual/basics/import_maps/",
"/runtime/manual/basics/env_variables/",
"/runtime/manual/basics/debugging_your_code/",
"/runtime/manual/basics/connecting_to_databases/",
"/runtime/manual/basics/react/",
"/runtime/manual/getting_started/installation/",
],
label: "Hello World",
id: "/runtime/",
},
"/runtime/getting_started/first_project/",
"/runtime/getting_started/setup_your_environment/",
"/runtime/getting_started/command_line_interface/",
],
},
{
title: "Modules and APIs",
title: "Fundamentals",
items: [
"/runtime/fundamentals/typescript/",
"/runtime/fundamentals/security/",
{
label: "Using & Publishing Modules",
items: [
Expand All @@ -42,6 +29,19 @@ export const sidebar = [
"/runtime/manual/advanced/http_imports/",
],
},
"/runtime/fundamentals/configuration/",
"/runtime/fundamentals/standard_library/",
"/runtime/fundamentals/testing/",
"/runtime/fundamentals/debugging/",
"/runtime/fundamentals/workspaces/",
"/runtime/fundamentals/web_frameworks/",
"/runtime/fundamentals/installation/",
"/runtime/fundamentals/stability/",
],
},
{
title: "Modules and APIs",
items: [
{
label: "Deno Runtime APIs",
items: [
Expand All @@ -51,7 +51,6 @@ export const sidebar = [
"/runtime/manual/runtime/import_meta_api/",
"/runtime/manual/runtime/ffi_api/",
"/runtime/manual/runtime/program_lifecycle/",
"/runtime/manual/runtime/stability/",
],
},
{
Expand Down Expand Up @@ -198,23 +197,6 @@ export const sidebar = [
},
],
},
{
label: "Testing",
items: [
"/runtime/manual/basics/testing/",
"/runtime/manual/basics/testing/assertions/",
"/runtime/manual/basics/testing/coverage/",
"/runtime/manual/basics/testing/mocking/",
"/runtime/manual/basics/testing/sanitizers/",
"/runtime/manual/basics/testing/documentation/",
"/runtime/manual/basics/testing/behavior_driven_development/",
"/runtime/manual/basics/testing/snapshot_testing/",
],
},
{
label: "Workspaces",
id: "/runtime/manual/basics/workspaces/",
},
{
label: "Vendoring",
id: "/runtime/manual/basics/vendoring/",
Expand Down Expand Up @@ -255,8 +237,6 @@ export const sidebar = [
{
label: "TypeScript in Deno",
items: [
"/runtime/manual/advanced/typescript/overview/",
"/runtime/manual/advanced/typescript/types/",
"/runtime/manual/advanced/typescript/configuration/",
"/runtime/manual/advanced/typescript/migration/",
"/runtime/manual/advanced/typescript/faqs/",
Expand Down Expand Up @@ -353,4 +333,4 @@ export const sidebar = [
] satisfies Sidebar;

export const sectionTitle = "Runtime";
export const sectionHref = "/runtime/manual/";
export const sectionHref = "/runtime/";
4 changes: 2 additions & 2 deletions runtime/manual/advanced/_category_.json → runtime/fundamentals/_category_.json
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"label": "Advanced",
"position": 8,
"label": "Fundamentals",
"position": 2,
"link": {
"type": "doc",
"id": "index"
Expand Down
3 changes: 2 additions & 1 deletion ...ual/getting_started/configuration_file.md → runtime/fundamentals/configuration.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
---
title: "`deno.json` configuration file"
title: "deno.json configuration file"
oldUrl: /runtime/manual/getting_started/configuration_file/
---

Deno supports a configuration file that allows you to customize the built-in
Expand Down
44 changes: 25 additions & 19 deletions runtime/manual/basics/debugging_your_code.md → runtime/fundamentals/debugging.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
---
title: "Debugging Your Code"
oldUrl: /runtime/manual/getting_started/debugging_your_code/
oldUrl:
- /runtime/manual/getting_started/debugging_your_code/
- /runtime/manual/basics/debugging_your_code/
---

Deno supports the [V8 Inspector Protocol](https://v8.dev/docs/inspector) used by
Expand All @@ -18,22 +20,26 @@ for example Chrome DevTools. Visit `chrome://inspect` in a Chromium derived
browser to connect Deno to the inspector server. This allows you to inspect your
code, add breakpoints, and step through your code.

```shell
```sh
deno run --inspect your_script.ts
```

> ⚠️ If you use the `--inspect` flag, the code will start executing immediately.
> If your program is short, you might not have enough time to connect the
> debugger before the program finishes execution. In such cases, try running
> with `--inspect-wait` or `--inspect-brk` flag instead, or add a timeout at the
> end of your code.
:::note

If you use the `--inspect` flag, the code will start executing immediately. If
your program is short, you might not have enough time to connect the debugger
before the program finishes execution. In such cases, try running with
`--inspect-wait` or `--inspect-brk` flag instead, or add a timeout at the end of
your code.

:::

## --inspect-wait

Before running the code, the `--inspect-wait` flag will pause execution until a
debugger is attached.

```shell
```sh
deno run --inspect-wait your_script.ts
```

Expand All @@ -45,7 +51,7 @@ additional breakpoints or evaluate expressions before resuming execution. **This
is the most commonly used inspect flag**. JetBrains and VSCode IDEs use this
flag by default.

```shell
```sh
deno run --inspect-brk your_script.ts
```

Expand All @@ -57,7 +63,7 @@ server.

Use the `--inspect-brk` flag to break execution on the first line:

```shell
```sh
$ deno run --inspect-brk --allow-read --allow-net jsr:@std/http@1.0.0-rc.5/file-server
Debugger listening on ws://127.0.0.1:9229/ws/1e82c406-85a9-44ab-86b6-7341583480b1
...
Expand All @@ -66,11 +72,11 @@ Debugger listening on ws://127.0.0.1:9229/ws/1e82c406-85a9-44ab-86b6-7341583480b
In a Chromium derived browser such as Google Chrome or Microsoft Edge, open
`chrome://inspect` and click `Inspect` next to target:

![chrome://inspect](../images/debugger1.jpg)
![chrome://inspect](./images/debugger1.jpg)

It might take a few seconds after opening the DevTools to load all modules.

![DevTools opened](../images/debugger2.jpg)
![DevTools opened](./images/debugger2.jpg)

You might notice that DevTools pauses execution on the first line of
`_constants.ts` instead of `file_server.ts`. This is expected behavior caused by
Expand All @@ -81,7 +87,7 @@ At this point all source code is available in the DevTools, so let's open up
`file_server.ts` and add a breakpoint there; go to "Sources" pane and expand the
tree:

![Open file_server.ts](../images/debugger3.jpg)
![Open file_server.ts](./images/debugger3.jpg)

_Looking closely you'll find duplicate entries for each file; one written
regularly and one in italics. The former is compiled source file (so in the case
Expand All @@ -90,7 +96,7 @@ source map for the file._

Next, add a breakpoint in the `listenAndServe` method:

![Break in file_server.ts](../images/debugger4.jpg)
![Break in file_server.ts](./images/debugger4.jpg)

As soon as we've added the breakpoint, DevTools automatically opens up the
source map file, which allows us step through the actual source code that
Expand All @@ -102,11 +108,11 @@ button to do so. You might even need to hit it twice!

Once our script is running, try send a request and inspect it in Devtools:

```console
```sh
curl http://0.0.0.0:4507/
```

![Break in request handling](../images/debugger5.jpg)
![Break in request handling](./images/debugger5.jpg)

At this point we can introspect the contents of the request and go step-by-step
to debug the code.
Expand All @@ -127,7 +133,7 @@ and enabled in Preferences / Settings | Plugins. For more information, see
You can debug Deno using your JetBrains IDE by right-clicking the file you want
to debug and selecting the `Debug 'Deno: <file name>'` option.

![Debug file](../images/jb-ide-debug.png)
![Debug file](./images/jb-ide-debug.png)

This will create a run/debug configuration with no permission flags set. If you
want to configure them, open your run/debug configuration and add the required
Expand All @@ -140,7 +146,7 @@ If you're having trouble connecting to the inspector, you can use the
will show you information like module resolution, network requests, and other
permission checks.

```shell
```sh
deno run --inspect-brk --log-level=debug your_script.ts
```

Expand All @@ -152,7 +158,7 @@ networking, and timers to JavaScript. The `--strace-ops` flag will print out all
ops that are being executed by Deno when a program is run along with their
timings.

```shell
```sh
deno run --strace-ops your_script.ts
```

Expand Down
0 runtime/manual/images/debugger1.jpg → runtime/fundamentals/images/debugger1.jpg
View file
File renamed without changes
0 runtime/manual/images/debugger2.jpg → runtime/fundamentals/images/debugger2.jpg
View file
File renamed without changes
0 runtime/manual/images/debugger3.jpg → runtime/fundamentals/images/debugger3.jpg
View file
File renamed without changes
0 runtime/manual/images/debugger4.jpg → runtime/fundamentals/images/debugger4.jpg
View file
File renamed without changes
0 runtime/manual/images/debugger5.jpg → runtime/fundamentals/images/debugger5.jpg
View file
File renamed without changes
0 runtime/manual/images/debugger7.jpg → runtime/fundamentals/images/debugger7.jpg
View file
File renamed without changes
1 change: 1 addition & 0 deletions ...me/manual/getting_started/installation.md → runtime/fundamentals/installation.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
---
title: Installation
oldUrl: /runtime/manual/getting_started/installation
---

Deno works on macOS, Linux, and Windows. Deno is a single binary executable. It
Expand Down
Loading

0 comments on commit 26e8f40

Please sign in to comment.