[Docs] Many docs improvements (#2171)

Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com>

Author: peterschmidt85

README.md

@@ -41,7 +41,7 @@ for AI workloads both in the cloud and on-prem, speeding up the development, tra
 To use `dstack` with your own cloud accounts, create the `~/.dstack/server/config.yml` file and 
 [configure backends](https://dstack.ai/docs/reference/server/config.yml). Alternatively, you can configure backends via the control plane UI after you start the server.
 
-You can skip backends configuration if you intend to run containers  only on your on-prem servers. Use [SSH fleets](https://dstack.ai/docs/concepts/fleets#ssh-fleets) for that.
+You can skip backends configuration if you intend to run containers  only on your on-prem servers. Use [SSH fleets](https://dstack.ai/docs/concepts/fleets#ssh) for that.
 
 ### Start the server
 

docker/server/README.md

@@ -39,7 +39,7 @@ Configuration is updated at ~/.dstack/config.yml
 ## Create SSH fleets
 
 If you want the `dstack` server to run containers on your on-prem servers,
-use [fleets](https://dstack.ai/docs/concepts/fleets#ssh-fleets).
+use [fleets](https://dstack.ai/docs/concepts/fleets#ssh).
 
 ## More information
 

docs/assets/stylesheets/extra.css

@@ -23,6 +23,11 @@
         font-size: 0.75rem;
     }
 }
+
+[dir=ltr] .md-typeset :is(.admonition,details) pre, [dir=ltr] .md-typeset :is(.admonition,details) :is(.admonition,details) {
+    margin-left: 32px;
+}
+
 @media screen and (max-width: 76.1875em) {
     .md-header {
         background-color: rgb(255, 255, 255);
@@ -160,7 +165,7 @@
     background-color: var(--md-default-fg-color);
 }
 
-[dir=ltr] .md-typeset :is(.admonition,details) {
+[dir=ltr] .md-typeset :is(details) {
     border-style: solid;
     /*border-width: 1px;*/
     border-width: 0;
@@ -170,6 +175,16 @@
     background: -webkit-linear-gradient(45deg, rgba(0, 42, 255, 0.1), rgb(0 114 255 / 1%), rgba(0, 42, 255, 0.05));
 }
 
+[dir=ltr] .md-typeset :is(.admonition) {
+    border-style: solid;
+    border-color: rgba(0, 0, 0, 0.87);
+    border-width: 1px;
+    border-radius: 6px;
+    box-shadow: none;
+    padding: .6rem .8rem;
+    /*background: -webkit-linear-gradient(45deg, rgba(0, 42, 255, 0.1), rgb(0 114 255 / 1%), rgba(0, 42, 255, 0.05));*/
+}
+
 .md-typeset iframe {
     border-radius: 6px;
 }
@@ -178,7 +193,7 @@
     margin-left: 32px;
 }
 
-[dir=ltr] .md-typeset :is(.admonition,details):not(blockquote) > :is(.highlight,.termy,.md-typeset__scrollwrap,p,h4,h3,.tabbed-set):not(.admonition-title) {
+[dir=ltr] .md-typeset :is(.admonition,details):not(blockquote) > :is(.md-typeset__scrollwrap,p,h4,h3,.tabbed-set):not(.admonition-title) {
     padding-left: 32px;
 }
 
@@ -445,7 +460,7 @@
     color: rgba(0,0,0,0.87);
 }
 
-.md-typeset :not(pre) :is(h1, h2, h3, h4) > code {
+.md-typeset :not(pre) :is(h1, h2, h3, h4, h5, h6) > code {
     color: inherit;
     background: inherit;
     padding: 0;
@@ -455,7 +470,7 @@ h4.doc-heading {
     font-size: inherit;
 }
 
-.md-typeset :not(pre, h1, h2, h3, h4) > code {
+.md-typeset :not(pre, h1, h2, h3, h4, h5, h6) > code {
     background-color: rgba(163, 68, 215, 0.05);
     /*border: 1px solid #dce0e6;*/
     border-radius: 2px;
@@ -467,27 +482,27 @@ h4.doc-heading {
     margin: 0 4px;
 }
 
-.md-typeset :is(h1, h2, h3, h4) > code {
+.md-typeset :is(h1, h2, h3, h4, h5, h6) > code {
     background-color: inherit;
     color: inherit;
     /*padding: 0;
     margin: 0;*/
 }
-.md-typeset :is(h1, h2, h3, h4) > a > code {
+.md-typeset :is(h1, h2, h3, h4, h5, h6) > a > code {
     font-size: inherit;
     color: inherit;
 }
 
 
-.md-typeset :is(table) :not(pre, h1, h2, h3, h4) > code {
+.md-typeset :is(table) :not(pre, h1, h2, h3, h4, h5, h6) > code {
     font-size: .85em;
 }
 
-.md-typeset :not(pre, h1, h2, h3, h4) > code {
+.md-typeset :not(pre, h1, h2, h3, h4, h5, h6) > code {
     font-size: 0.65rem;
 }
 
-.md-typeset :not(pre, h1, h2, h3, h4) > a code {
+.md-typeset :not(pre, h1, h2, h3, h4, h5, h6) > a code {
     color: #ce00ff;
 }
 
@@ -639,7 +654,7 @@ code .md-code__nav:hover .md-code__button {
     /*letter-spacing: 0;*/
 }
 
-.md-typeset h1, .md-typeset h2, .md-typeset h3, .md-typeset h4, .md-typeset h5 {
+.md-typeset h1, .md-typeset h2, .md-typeset h3, .md-typeset h4, .md-typeset h5, .md-typeset h6 {
     font-weight: 800;
     letter-spacing: -1px;
     color: rgb(0, 0, 0);
@@ -654,6 +669,10 @@ code .md-code__nav:hover .md-code__button {
     font-size: 17px;
 }
 
+.md-typeset h6  {
+    font-size: 15px;
+}
+
 .md-typeset h3 {
     font-size: 21.5px;
     margin-block-end: 0;
@@ -1087,7 +1106,7 @@ html .md-footer-meta.md-typeset a:is(:focus,:hover) {
     background: none;
     z-index: 1;
     padding: 5px;
-    border-radius: 12px;
+    border-radius: 6px;
     border: 1px solid black;
     bottom: -0.7px;
     top: -0.7px;
@@ -1124,7 +1143,7 @@ html .md-footer-meta.md-typeset a:is(:focus,:hover) {
     height: 100%;
     background: -webkit-linear-gradient(45deg, rgba(0, 42, 255, 0.025), rgb(0 114 255 / 0.25%), rgba(0, 42, 255, 0.0125));
     z-index: 1;
-    border-radius: 12px;
+    border-radius: 6px;
     border: 0.5px solid rgba(0,0,0, 0.5);
     overflow: unset;
 }
@@ -1198,7 +1217,7 @@ html .md-footer-meta.md-typeset a:is(:focus,:hover) {
         margin: 1em .8rem;
     }
 
-    .md-typeset .tabbed-block :is(h1, h2, h3, h4, h5) {
+    .md-typeset .tabbed-block :is(h1, h2, h3, h4, h5, h6) {
         margin-left: .8rem;
     }
 

docs/blog/archive/say-goodbye-to-managed-notebooks.md

@@ -98,4 +98,4 @@ You can securely access the cloud development environment with the desktop IDE o
 ![](../../assets/images/dstack-vscode-jupyter.png){ width=800 }
 
 !!! info "Learn more"
-    Check out our [guide](../../docs/dev-environments.md) for running dev environments in your cloud.
+    Check out our [guide](../../docs/concepts/dev-environments.md) for running dev environments in your cloud.

docs/blog/posts/amd-mi300x-inference-benchmark.md

@@ -11,7 +11,7 @@ categories:
 
 # Benchmarking Llama 3.1 405B on 8x AMD MI300X GPUs
 
-At `dstack`, we've been adding support for AMD GPUs with [SSH fleets](../../docs/concepts/fleets.md#ssh-fleets), 
+At `dstack`, we've been adding support for AMD GPUs with [SSH fleets](../../docs/concepts/fleets.md#ssh), 
 so we saw this as a great chance to test our integration by benchmarking AMD GPUs. Our friends at 
 [Hot Aisle :material-arrow-top-right-thin:{ .external }](https://hotaisle.xyz/){:target="_blank"}, who build top-tier 
 bare metal compute for AMD GPUs, kindly provided the hardware for the benchmark.
@@ -35,7 +35,7 @@ Here is the spec of the bare metal machine we got:
 ??? info "Set up an SSH fleet"
 
     Hot Aisle provided us with SSH access to the machine. To make it accessible via `dstack`,
-    we created an [SSH fleet](../../docs/concepts/fleets.md#ssh-fleets) using the following configuration:
+    we created an [SSH fleet](../../docs/concepts/fleets.md#ssh) using the following configuration:
 
     <div editor-title="hotaisle.dstack.yml"> 
 
@@ -216,7 +216,7 @@ If you have questions, feedback, or want to help improve the benchmark, please r
 is the primary sponsor of this benchmark, and we are sincerely grateful for their hardware and support.  
 
 If you'd like to use top-tier bare metal compute with AMD GPUs, we recommend going
-with Hot Aisle. Once you gain access to a cluster, it can be easily accessed via `dstack`'s [SSH fleet](../../docs/concepts/fleets.md#ssh-fleets) easily.
+with Hot Aisle. Once you gain access to a cluster, it can be easily accessed via `dstack`'s [SSH fleet](../../docs/concepts/fleets.md#ssh) easily.
 
 ### RunPod
 If you’d like to use on-demand compute with AMD GPUs at affordable prices, you can configure `dstack` to

docs/blog/posts/amd-on-runpod.md

@@ -39,7 +39,7 @@ you can now specify an AMD GPU under `resources`. Below are a few examples.
 ## Configuration
 
 === "Service"
-    Here's an example of a [service](../../docs/services.md) that deploys
+    Here's an example of a [service](../../docs/concepts/services.md) that deploys
     Llama 3.1 70B in FP16 using [TGI :material-arrow-top-right-thin:{ .external }](https://huggingface.co/docs/text-generation-inference/en/installation_amd){:target="_blank"}.
 
     <div editor-title="examples/deployment/tgi/amd/service.dstack.yml"> 
@@ -71,7 +71,7 @@ you can now specify an AMD GPU under `resources`. Below are a few examples.
     </div>
 
 === "Dev environment"
-    Here's an example of a [dev environment](../../docs/dev-environments.md) using
+    Here's an example of a [dev environment](../../docs/concepts/dev-environments.md) using
     [TGI :material-arrow-top-right-thin:{ .external }](https://huggingface.co/docs/text-generation-inference/en/installation_amd){:target="_blank"}'s
     Docker image:
 

docs/blog/posts/dstack-sky.md

@@ -73,8 +73,8 @@ Continue? [y/n]:
 You can use both on-demand and spot instances without needing to manage quotas, as they are automatically handled
 for you.
 
-With `dstack Sky` you can use all of `dstack`'s features, incl. [dev environments](../../docs/dev-environments.md), 
-[tasks](../../docs/tasks.md), [services](../../docs/services.md), and 
+With `dstack Sky` you can use all of `dstack`'s features, incl. [dev environments](../../docs/concepts/dev-environments.md), 
+[tasks](../../docs/concepts/tasks.md), [services](../../docs/concepts/services.md), and 
 [fleets](../../docs/concepts/fleets.md).
 
 To publish services, the open-source version requires setting up a gateway with your own domain. 

docs/blog/posts/tpu-on-gcp.md

@@ -211,8 +211,8 @@ Note, `v5litepod` is optimized for fine-tuning transformer-based models. Each co
 1. Browse [Optimum TPU :material-arrow-top-right-thin:{ .external }](https://github.com/huggingface/optimum-tpu){:target="_blank"},
    [Optimum TPU TGI :material-arrow-top-right-thin:{ .external }](https://github.com/huggingface/optimum-tpu/tree/main/text-generation-inference){:target="_blank"} and
    [vLLM :material-arrow-top-right-thin:{ .external }](https://docs.vllm.ai/en/latest/getting_started/tpu-installation.html){:target="_blank"}.
-2. Check [dev environments](../../docs/dev-environments.md), [tasks](https://dstack.ai/docs/tasks), 
-   [services](../../docs/services.md), and [fleets](../../docs/concepts/fleets.md).
+2. Check [dev environments](../../docs/concepts/dev-environments.md), [tasks](https://dstack.ai/docs/tasks), 
+   [services](../../docs/concepts/services.md), and [fleets](../../docs/concepts/fleets.md).
 
 !!! info "Multi-host TPUs"
     If you’d like to use `dstack` with more than eight TPU cores, upvote the corresponding

docs/blog/posts/volumes-on-runpod.md

@@ -18,7 +18,7 @@ deploying a model on RunPod.
 
 <!-- more -->
 
-Suppose you want to deploy Llama 3.1 on RunPod as a [service](../../docs/services.md):
+Suppose you want to deploy Llama 3.1 on RunPod as a [service](../../docs/concepts/services.md):
 
 <div editor-title="examples/llms/llama31/tgi/service.dstack.yml">
 
@@ -115,7 +115,7 @@ env:
 commands:
   - text-generation-launcher
 port: 80
-# Register the mdoel
+# Register the model
 model: meta-llama/Meta-Llama-3.1-8B-Instruct
 
 # Uncomment to leverage spot instances
@@ -131,9 +131,9 @@ In this case, `dstack` attaches the specified volume to each new replica. This e
 once, reducing cold start time in proportion to the model size.
 
 A notable feature of RunPod is that volumes can be attached to multiple containers simultaneously. This capability is
-particularly useful for autoscalable services or distributed tasks.
+particularly useful for auto-scalable services or distributed tasks.
 
 Using [volumes](../../docs/concepts/volumes.md) not only optimizes inference cold start times but also enhances the
 efficiency of data and model checkpoint loading during training and fine-tuning.
-Whether you're running [tasks](../../docs/tasks.md) or [dev environments](../../docs/dev-environments.md), leveraging
+Whether you're running [tasks](../../docs/concepts/tasks.md) or [dev environments](../../docs/concepts/dev-environments.md), leveraging
 volumes can significantly streamline your workflow and improve overall performance.