docs: flatten navigation structure and rework content pages (denoland…

…#746)

Co-authored-by: Marvin Hagemeister <[email protected]>

_components/Header.tsx

@@ -45,7 +45,7 @@ export default function Header({
           <HeaderItem
             url={url}
             activeOn="/runtime"
-            href="/runtime/manual"
+            href="/runtime/"
             name="Runtime Manual"
             hideOnMobile
           />

_config.ts

@@ -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");

deploy/tutorials/simple-api.md

@@ -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/
 ```
 

examples.page.tsx

@@ -7,7 +7,7 @@ export const sidebar = [
     items: [
       {
         label: "Runtime Manual",
-        id: "/runtime/manual/",
+        id: "/runtime/",
       },
       {
         label: "Examples",

go.json

@@ -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"
 }

index.page.tsx

@@ -8,7 +8,7 @@ export const sidebar = [
     items: [
       {
         label: "Runtime Manual",
-        id: "/runtime/manual/",
+        id: "/runtime/",
       },
       {
         label: "Examples",
@@ -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
@@ -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"
               />
 
@@ -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>

runtime/_data.ts

@@ -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: [
@@ -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: [
@@ -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/",
         ],
       },
       {
@@ -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/",
@@ -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/",
@@ -353,4 +333,4 @@ export const sidebar = [
 ] satisfies Sidebar;
 
 export const sectionTitle = "Runtime";
-export const sectionHref = "/runtime/manual/";
+export const sectionHref = "/runtime/";

runtime/manual/advanced/_category_.json → runtime/fundamentals/_category_.json

@@ -1,6 +1,6 @@
 {
-  "label": "Advanced",
-  "position": 8,
+  "label": "Fundamentals",
+  "position": 2,
   "link": {
     "type": "doc",
     "id": "index"

runtime/manual/getting_started/configuration_file.md → runtime/fundamentals/configuration.md

@@ -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

runtime/manual/basics/debugging_your_code.md → runtime/fundamentals/debugging.md

@@ -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
@@ -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
 ```
 
@@ -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
 ```
 
@@ -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/[email protected]/file-server
 Debugger listening on ws://127.0.0.1:9229/ws/1e82c406-85a9-44ab-86b6-7341583480b1
 ...
@@ -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
@@ -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
@@ -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
@@ -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.
@@ -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
@@ -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
 ```
 
@@ -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
 ```
 

runtime/manual/getting_started/installation.md → runtime/fundamentals/installation.md

@@ -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