From a528aa8cda86f6bddf2138faf966c6438e26e8c8 Mon Sep 17 00:00:00 2001
From: Penelope Yong <penelopeysm@gmail.com>
Date: Sat, 2 Nov 2024 20:37:46 +0000
Subject: [PATCH] Expand section on local rendering in README (#545)

---
 README.md | 25 ++++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 139153703..9a7c1a20d 100644
--- a/README.md
+++ b/README.md
@@ -44,14 +44,29 @@ Once you have the prerequisite installed, you can follow these steps:
     quarto render
     ```
 
-    This will render the full website in `_site` folder.
+    This will build the entire documentation and place the output in the `_site` folder.
+    You can then view the rendered website by launching a HTTP server from that directory, e.g. using Python:
 
-    It is also possible to render a single tutorial or `qmd` file without compiling the entire site. This is often helpful to speed up compilation when editing a single docs page. To do this, pass the `qmd` file as an argument to `quarto render`:
-
-    ```
-    quarto render path/to/index.qmd
+    ```bash
+    cd _site
+    python -m http.server 8000
     ```
 
+    Then, navigate to http://localhost:8000/ in your web browser.
+
+    Note that rendering the entire documentation site can take a long time (usually multiple hours).
+    If you wish to speed up local rendering, there are two options available:
+
+    - Download the most recent `_freeze` folder from the [GitHub releases of this repo](https://github.com/turinglang/docs/releases), and place it in the root of the project.
+      This will allow Quarto to reuse the outputs of previous computations for any files which have not been changed since that `_freeze` folder was created.
+
+    - Alternatively, render a single tutorial or `qmd` file without compiling the entire site.
+      To do this, pass the `qmd` file as an argument to `quarto render`:
+
+      ```
+      quarto render path/to/index.qmd
+      ```
+
 ## Troubleshooting build issues
 
 As described in the [Quarto docs](https://quarto.org/docs/computations/julia.html#using-the-julia-engine), Quarto's Julia engine uses a worker process behind the scenes.