Some edits on getting started, splits between guides and reference, a…

…dded reference and guides content, small edits on home, scrollbar on table of contents

src/components/TableOfContents.astro

@@ -29,7 +29,7 @@ function buildToc(headings: BasicHeading[]) {
 			toc.push(heading);
 		} else if (
 			parentHeadings.get(heading.depth - 1) != undefined &&
-			heading.depth < 4
+			heading.depth < 5
 		) {
 			parentHeadings.get(heading.depth - 1).subheadings.push(heading);
 		}
@@ -38,9 +38,58 @@ function buildToc(headings: BasicHeading[]) {
 }
 ---
 
-<nav>
-	<h5 class="font-semibold mb-1 leading-7 text-stone-300">On this page</h5>
-	<ol>
-		{toc.map((heading) => <TableOfContentsHeading heading={heading} />)}
-	</ol>
-</nav>
+<aside
+	is="docs-sidebar"
+	class="bg-stone-800 lg:bg-stone-900 fixed lg:sticky top-[65px] z-10 px-8 pb-8 w-full sm:w-80 h-[calc(100vh-4rem)] overflow-y-auto lg:text-sm"
+>
+	<nav>
+		<h5 class="font-semibold mb-1 leading-7 text-stone-300">On this page</h5>
+		<ol>
+			{toc.map((heading) => <TableOfContentsHeading heading={heading} />)}
+		</ol>
+	</nav>
+</aside>
+
+<script>
+	function loadPos(): number {
+		const pos = parseFloat(
+			sessionStorage.getItem("docs-sidebar-scroll") || "0",
+		);
+		if (isNaN(pos)) return 0;
+		return pos;
+	}
+
+	function savePos(pos: number) {
+		sessionStorage.setItem("docs-sidebar-scroll", pos.toString());
+	}
+	class TableOfContents extends HTMLElement {
+		constructor() {
+			super();
+
+			// Maintain scroll position across page reloads
+			this.scrollTop = loadPos();
+			window.addEventListener("beforeunload", () => {
+				savePos(this.scrollTop);
+			});
+
+			// If the active item is out of view, scroll so it is in the center
+			const activeEl = this.querySelector<HTMLLIElement>("li[data-is-active]");
+			if (activeEl) {
+				const scrollRect = this.getBoundingClientRect();
+				const activeRect = activeEl.getBoundingClientRect();
+
+				const top = activeEl.offsetTop;
+				const bottom = top - scrollRect.height + activeRect.height;
+
+				if (this.scrollTop > top || this.scrollTop < bottom) {
+					this.scrollTop = top - scrollRect.height / 2 + activeRect.height / 2;
+				}
+			} else {
+				console.warn("docs-sidebar didn't find active link");
+			}
+		}
+	}
+	customElements.define("tableOfContents", TableOfContents, {
+		extends: "aside",
+	});
+</script>

src/content/docs/cheerpj2/03-getting-started/00-Java-app.md

@@ -2,17 +2,29 @@
 title: Run a Java Application
 ---
 
-CheerpJ can run a Java application in the browser with little to no modifications. This page will help you getting started with CheerpJ and running your first Java application in the browser.
+CheerpJ can run a Java application in the browser with to no modifications. This page will help you getting started with CheerpJ and running your first Java application in the browser.
+
+Java source code is not needed to use CheerpJ. If you are building your own application you should already have its `.jar` file(s).
 
 **To get started you will need:**
 
-- Your java application file(s)
+- Your java application file(s). You can also use this [TextDemo.jar](https://docs.oracle.com/javase/tutorialJWS/samples/uiswing/TextDemoProject/TextDemo.jar) sample.
 - An HTML file where your Java app will be wrapped
 - A simple HTTP server to test your webpage locally
 
-## 1. Create a basic HTML file
+## 1. Create a project directory
+
+Let's start by creating a project folder where all your files will be. Please copy your java and future HTML files here.
+
+```shell
+
+mkdir directory_name
+
+```
+
+## 2. Create a basic HTML file
 
-Let's start by creating a simplet HTML file like the following example. Please notice the CheerpJ runtime environment has been integrated. In this example we are assuming your HTML file and your .jar files are under the same directory.
+Let's create a basic HTML file like the following example. Please notice the CheerpJ runtime environment has been integrated and initialized. In this example we are assuming your HTML file and your `.jar` files are under the project directory you just created.
 
 ```html title="index.html" {6, 9-16}
 <!doctype html>
@@ -34,15 +46,23 @@ Let's start by creating a simplet HTML file like the following example. Please n
 </html>
 ```
 
-## 2. Host your page
+Alternatively, if your application is designed to be executed with the command `java -jar` you can replace `cheerpjRunMain()` for the following line:
+
+```js
+cheerpjRunJar("/app/my_application_archive.jar");
+```
+
+## 3. Host your page
 
 You can now serve this web page on a simple HTTP server, such as the http-server utility.
 
 ```shell
 npm install http-server
-http-server [path] [options]
+http-server -p 8080
 ```
 
+> To test CheerpJ you _must_ use a local web server. Opening the `.html` page directly from the disk (for example, by double-clicking on it) is **_not supported_**. This is a very common mistake for first time users.
+
 ## What's going on?
 
 - CheerpJ loader is included from our cloud runtime as
@@ -52,6 +72,10 @@ http-server [path] [options]
 - `cheerpjRunMain()` executes the `main` method of `ChangeThisToYourClassName`. The second parameter is a `:` separated list of `.jar` files where application classes can be found (the classpath).
 - The `/app/` is a virtual file system mount point that reference the root of the web server this page is loaded from.
 
+## The result
+
+You will see the CheerpJ display on your browser with some loading messages before showing your application running. Depending on your application and the optimizations applied, this could take just a few seconds.
+
 ## Further reading
 
 - [AOT optimization](/cheerpj2/guides/AOT-optimization)

src/content/docs/cheerpj2/03-getting-started/01-Java-applet.mdx

@@ -9,7 +9,7 @@ CheerpJ can run Java applets in the browser seamlessly. This page will help you
 **There are two different ways to run a Java Applet in the browser:**
 
 - Running your own Java applet using the CheerpJ runtime environment and the `<cheerpj-applet>` tag in your own webpage.
-- Running a public applet using the [CheerpJ Applet Runner](https://chrome.google.com/webstore/detail/cheerpj-applet-runner-bet/) Chrome extension for applets integrated with the applet tag `<applet>` in public websites.
+- Running a public applet using the [CheerpJ Applet Runner](https://chrome.google.com/webstore/detail/cheerpj-applet-runner-bet/) Chrome extension for applets integrated with the applet tag `<applet>` on public websites.
 
 ## Running your own applet
 
@@ -52,19 +52,19 @@ You can now serve this web page on a simple HTTP server, such as the http-server
 
 ```shell
 npm install http-server
-http-server [path] [options]
+http-server -p 8080
 ```
 
 ### What's going on?
 
-- The `cheerpjInit({enablePreciseAppletArchives:true});` initializes CheerpJ runtime environment indicating we are running an applet and not an standalone app.
+- The `cheerpjInit({enablePreciseAppletArchives:true});` initializes CheerpJ runtime environment indicating we are loading an applet.
 - The `<cheerpj-applet>` tag specifies the code base in a similar manner as the now deprecated `<applet>` tag.
 
 > To avoid potential conflicts with native Java we recommend replacing the original HTML tag with `cheerpj-` prefixed version. You should use `<cheerpj-applet>`, `<cheerpj-object>` or `<cheerpj-embed>` depending on the original tag.
 
 ## Running a public applet
 
-### Step 1: Install the CheerpJ applet runner
+### 1. Install the CheerpJ applet runner
 
 CheerpJ Applet Runner is available for Chrome and Edge.
 
@@ -85,8 +85,17 @@ CheerpJ Applet Runner is available for Chrome and Edge.
 
 </div>
 
-### Step 2: Go to a website with an applet
+### 2. Go to a website with an applet
 
 Visit a page with a Java applet, [such as this one](http://www.neilwallis.com/projects/java/water/index.php) and click on the CheerpJ Applet Runner icon in the toolbar and enable CheerpJ.
 
 ![](/cheerpj2/assets/cheerpj_applet_demo.gif)
+
+## The result
+
+You will see the CheerpJ display on your browser with some loading messages before showing your applet running. Depending on your application and the optimizations applied, this could take just a few seconds.
+
+## Further reading
+
+- [AOT optimization](/cheerpj2/guides/AOT-optimization)
+- [Runtime API](http://localhost:3000/cheerpj2/reference/Runtime-API)