From b0f38a1f5533e54a2e1f83fd414dd387c58181cd Mon Sep 17 00:00:00 2001
From: Ruben Verborgh <ruben@verborgh.org>
Date: Wed, 28 Jul 2021 21:36:48 +0200
Subject: [PATCH] docs: Add starting guidance to welcome document.

---
 README.md                                     |  2 +-
 templates/root/index.html                     | 67 +++++++++++++++----
 templates/styles/main.css                     | 42 +++++++++---
 .../integration/LdpHandlerWithoutAuth.test.ts |  2 +-
 4 files changed, 89 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index a0a02f385..3e3b7d962 100644
--- a/README.md
+++ b/README.md
@@ -93,7 +93,7 @@ to some commonly used settings:
 | `--rootFilePath, -f`   | `./`                      | Root folder of the server, when using a file-based configuration.                                                               |
 | `--sparqlEndpoint, -s` |                           | URL of the SPARQL endpoint, when using a quadstore-based configuration.                                                         |
 | `--showStackTrace, -t` | false                     | Enables detailed logging on error pages.                                                                                        |
-| `--podConfigJson`      | `./pod-config.json`       | Path to the file that keeps track of dynamic pod configurations.                                                                |
+| `--podConfigJson`      | `./pod-config.json`       | Path to the file that keeps track of dynamic Pod configurations.                                                                |
 | `--mainModulePath, -m` |                           | Path from where Components.js will start its lookup when initializing configurations.
 
 ### 🧶 Custom configurations
diff --git a/templates/root/index.html b/templates/root/index.html
index 2611592c2..91bb1b163 100644
--- a/templates/root/index.html
+++ b/templates/root/index.html
@@ -12,29 +12,72 @@
     <h1>Community Solid Server</h1>
   </header>
   <main>
-    <h1>Welcome to the Community Solid Server</h1>
+    <h1>Welcome to Solid</h1>
     <p>
       This server implements
-      the <a href="https://solid.github.io/specification/protocol">Solid protocol</a>,
-      so you can set your own Solid pods.
+      the <a href="https://solid.github.io/specification/protocol">Solid protocol</a>
+      so you can create your own <a href="https://solidproject.org/about">Solid Pod</a>
+      and identity.
+    </p>
+
+    <h2 id="users">Getting started as a <em>user</em></h2>
+    <p>
+      <strong><a href="/idp/register/">Sign up</a> for an account</strong>
+      to get started with your own Pod and WebID.
     </p>
     <p>
-      Some things you can try:
+      The <em>default</em> configuration stores data only in memory,
+      so be sure to choose a configuration that saves data to disk.
+      If you are exposing this server publicly,
+      <a href="#public">read the guidelines below</a>.
+    </p>
+
+    <h2 id="developers">Getting started as a <em>developer</em></h2>
+    <p>
+      The <em>default</em> server configuration includes
+      this <strong>ready-to-use root Pod</strong> you're looking at.
+      That way, you don't need to create an account
+      to read and write data or to test apps.
+    </p>
+    <p>
+      You can easily choose any folder on your disk
+      to expose as the root Pod.
+      <br>
+      Use the <code>--help</code> switch to learn more.
+    </p>
+
+    <h2 id="public">Making this server public</h2>
+    <p>
+      Before making this server public,
+      you might want to <strong>disable certain convenience features</strong>
+      so they remain only accessible to you:
     </p>
     <ul>
       <li>
-        Read or write documents in the <strong>default pod</strong>.
-        <ul>
-          <li>This is the pod you are reading from now.</li>
-          <li>Anyone can read or write;
-              update the <a href="/.acl">access controls</a> to change this.</li>
-          <li>You can disable the default pod in the configuration.</li>
-        </ul>
+        Modify or delete this welcome document
+        at <a href="index.html"><code>index.html</code></a>.
       </li>
       <li>
-        <strong>Create your own</strong> pod by <a href="/idp/register/">registering</a>.
+        Prevent public write and control access to the root Pod
+        by modifying <a href=".acl"><code>.acl</code></a>.
+      </li>
+      <li>
+        Disable Pod registration
+        by <a href="https://github.com/solid/community-server/blob/main/config/identity/README.md">changing
+          the configuration</a>.
       </li>
     </ul>
+
+    <h2>Have a wonderful Solid experience</h2>
+    <p>
+      <strong>Learn more about Solid
+      at <a href="https://solidproject.org/">solidproject.org</a>.</strong>
+    </p>
+    <p>
+      You are warmly invited
+      to <a href="https://github.com/solid/community-server/discussions">share your experiences</a>
+      and to <a href="https://github.com/solid/community-server/issues">report any bugs</a> you encounter.
+    </p>
   </main>
   <footer>
     <p>
diff --git a/templates/styles/main.css b/templates/styles/main.css
index bd089bf64..0a0c6058c 100644
--- a/templates/styles/main.css
+++ b/templates/styles/main.css
@@ -14,7 +14,8 @@
 html {
   --solid-purple: #7c4dff;
   --solid-blue: #18a9e6;
-  --solid-gray: #8a8a8a;
+  --solid-dark: #162542;
+  --solid-gray: #6a6a6a;
 
   height: 100%;
 
@@ -26,20 +27,27 @@ html {
 }
 
 body, input, button {
-  font: 12pt/1.3 Raleway, sans-serif;
+  font: 12pt/1.6 Raleway, sans-serif;
   font-weight: 300;
-  color: #222222;
+  color: var(--solid-dark);
 }
 
 body {
-  max-width: 750px;
+  box-sizing: border-box;
+  max-width: 780px;
   margin: 2em auto;
-  padding: 1em 2em;
+  padding: 2em 3em 1em;
 
   background: white;
   box-shadow: 5px 5px 2px rgba(0, 0, 0, .1);
   border-radius: 3px;
 }
+@media (max-width: 800px) {
+  body {
+    margin: 0;
+    padding: 1em 2em;
+  }
+}
 
 header {
   margin: 1em 0 2em;
@@ -52,25 +60,35 @@ header {
 header h1 {
   margin: 0;
 
-  font-size: 3.33em;
+  font-size: 3em;
+  line-height: 1;
   letter-spacing: .25px;
   font-weight: 600;
 }
 header img {
   width: 100%;
+  margin-bottom: -.5em;
 }
 
 main h1 {
   margin: 1em 0 0;
-  font-weight: 600;
+  font-weight: 700;
 }
 main h2 {
-  margin: 1.5em 0 0;
-  font-weight: 500;
+  margin: 1em 0 0;
+  font-weight: 600;
+  color: var(--solid-gray);
+}
+main p {
+  margin: .75em 0;
+}
+main h1 + p,
+main h2 + p {
+  margin-top: .25em;
 }
 
 footer {
-  margin-top: 1em;
+  margin-top: 2em;
   text-align: right;
   font-size: 90%;
   color: #666666;
@@ -96,6 +114,9 @@ code {
   font-size: 90%;
 }
 
+ul {
+  margin: .75em 0;
+}
 li {
   margin: .5em 0;
 }
@@ -191,6 +212,7 @@ ul.container > li.container > a {
 ol.breadcrumbs {
   list-style: none;
   padding: 0;
+  margin: 0 0 0 .25em;
   font-size: 90%;
 }
 ol.breadcrumbs > li {
diff --git a/test/integration/LdpHandlerWithoutAuth.test.ts b/test/integration/LdpHandlerWithoutAuth.test.ts
index d498b0442..be437ab72 100644
--- a/test/integration/LdpHandlerWithoutAuth.test.ts
+++ b/test/integration/LdpHandlerWithoutAuth.test.ts
@@ -75,7 +75,7 @@ describe.each(stores)('An LDP handler allowing all requests %s', (name, { storeC
   it('can read the root container index page when asking for HTML.', async(): Promise<void> => {
     const response = await getResource(baseUrl, { accept: 'text/html' }, { contentType: 'text/html' });
 
-    await expect(response.text()).resolves.toContain('Welcome to the Community Solid Server');
+    await expect(response.text()).resolves.toContain('Welcome to Solid');
     expect(response.headers.get('link')).toContain(`<${PIM.Storage}>; rel="type"`);
   });