docs: add Docker instructions to README.md

README.md

@@ -1,13 +1,16 @@
-# Development
+# help.keyman.com
+
+This is the source for the website https://help.keyman.com/. This site runs on
+Apache in a Docker container.
 
 ## Documentation sources
 
 Many of the pages on this site are deployed from other repositories and should
 be edited in the source repository rather than here:
 
-* From https://github.com/keymanapp/keyboards:
-  * /keyboard
-* From https://github.com/keymanapp/keyman (see [resources/build/help-keyman-com.sh](https://github.com/keymanapp/keyman/blob/master/resources/build/help-keyman-com.sh)):
+* From https://github.com/keymanapp/keyboards (deployed when PRs are merged):
+  * /keyboard/
+* From https://github.com/keymanapp/keyman (see [resources/build/help-keyman-com.sh]):
   * /products/android/
   * /products/iphone-and-ipad/
   * /products/linux/
@@ -20,43 +23,101 @@ be edited in the source repository rather than here:
   * /developer/engine/windows/
   * /developer/core/
 
-## How to run help.keyman.com locally with Apache on Docker
+## Other Keyman websites
 
-Previously, the site was run in IIS, but is now migrated to Apache. The Docker image is configured to host the site that can be accessed at http://localhost:8055.
+* **[api.keyman.com]** - database backend for Keyman websites
+* **[help.keyman.com]** - documentation home for Keyman
+* **[keyman.com]** - Keyman home
+* **[keymanweb.com]** - KeymanWeb online keyboard
+* **[s.keyman.com]** - static Javascript, font, and related resources
+* **[website-local-proxy]** - run all Keyman sites on localhost on the same port
 
-If you have [website-local-proxy](https://github.com/keymanapp/website-local-proxy) running, the help site is available at
-http://help.keyman.com.localhost.
+## How to run help.keyman.com locally
 
-### Pre-requisites
+When run locally, this site can be accessed at http://localhost:8055 or
+http://help.keyman.com.localhost:8055.
 
-#### All host machines
+**Recommended:** Use [website-local-proxy] to run multiple keyman.com sites
+all from the same port (default port 80).
 
-The host machine needs the following:
-* [Git](https://git-scm.com/downloads)
-* Bash (on Windows, you can use Git Bash that comes with [Git](https://git-scm.com/download/win))
-* [Docker Desktop](https://docs.docker.com/get-docker/)
+**Recommended:** Use [shared-sites] to control startup and shutdown of all
+keyman.com sites together.
 
-#### Additional steps
-On Windows host machines, do one of these two options:
-* [Enable Hyper-V on Windows 11](https://techcommunity.microsoft.com/t5/educator-developer-blog/step-by-step-enabling-hyper-v-for-use-on-windows-11/ba-p/3745905)
-* [WSL2](https://ubuntu.com/tutorials/install-ubuntu-on-wsl2-on-windows-10#1-overview)
+### Prerequisites
 
-### Builder actions
+The host machine needs the following apps installed:
+* [Git]
+* Bash 5.x (on Windows, you can use Git Bash that comes with [Git])
+* [Docker Desktop]
 
-#### Stop the Docker container
-1. Run `./build.sh stop`
+  <details>
+  <summary>Configuration of Docker on Windows</summary>
+
+    On Windows machines, you can setup Docker in two different ways, either of
+    which should work:
+    * [Enable Hyper-V on Windows 11](https://techcommunity.microsoft.com/t5/educator-developer-blog/step-by-step-enabling-hyper-v-for-use-on-windows-11/ba-p/3745905)
+    * [WSL2](https://ubuntu.com/tutorials/install-ubuntu-on-wsl2-on-windows-10#1-overview)
+
+  </details>
+
+### Actions
 
 #### Build the Docker image
-1. Run `./build.sh build`.
+
+The first time you want to start up the site, or if there have been Docker
+configuration changes, you will need to rebuild the Docker images. Start a bash
+shell, and from this folder, run:
+
+```sh
+./build.sh build
+```
 
 #### Start the Docker container
-1. Run `./build.sh start --debug`.
 
-After this, you can access the help.keyman site at http://localhost:8055
+To start up the website, in bash, run:
+
+```sh
+./build.sh start --debug
+```
+
+Once the container starts, you can access the help.keyman.com site at
+http://localhost:8055 or http://help.keyman.com.localhost:8055
+
+#### Stop the Docker container
+
+In bash, run:
+
+```sh
+./build.sh stop
+```
 
 #### Remove the Docker container and image
-1. Run `./build.sh clean`.
+
+In bash, run:
+
+```sh
+./build.sh clean
+```
 
 #### Running tests
-Checks for broken links
-1. Run `./build.sh test`
+
+To check for broken links and .php file conformance, when the site is running,
+in bash, run:
+
+```sh
+./build.sh test
+```
+
+[resources/build/help-keyman-com.sh]: https://github.com/keymanapp/keyman/blob/master/resources/build/help-keyman-com.sh
+[Git]: https://git-scm.com/downloads
+[Docker Desktop]: https://docs.docker.com/get-docker/
+[shared sites]: https://github.com/keymanapp/shared-sites
+[api.keyman.com]: https://github.com/keymanapp/api.keyman.com
+[help.keyman.com]: https://github.com/keymanapp/help.keyman.com
+[keyman.com]: https://github.com/keymanapp/keyman.com
+[keymanweb.com]: https://github.com/keymanapp/keymanweb.com
+[s.keyman.com]: https://github.com/keymanapp/s.keyman.com
+[website-local-proxy]: https://github.com/keymanapp/website-local-proxy
+[shared-sites]: https://github.com/keymanapp/shared-sites
+[enable Hyper-V]: https://techcommunity.microsoft.com/t5/educator-developer-blog/step-by-step-enabling-hyper-v-for-use-on-windows-11/ba-p/3745905
+[enable WSL2]: https://ubuntu.com/tutorials/install-ubuntu-on-wsl2-on-windows-10#1-overview

_includes/includes/head.php

@@ -58,7 +58,9 @@
     <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,700italic,400italic' rel='stylesheet' type='text/css'>
   <script type='text/javascript' src='<?php echo cdn('js/keyrenderer.js'); ?>'></script>
   <script type="text/javascript">
-   // Add a script element as a child of the body
+    <?= KeymanHosts::Instance()->emitJavascriptConst(); ?>
+
+    // Add a script element as a child of the body
 
     function downloadJS(src) {
       var element = document.createElement("script");

cdn/dev/js/kbd-docs.js

@@ -181,7 +181,7 @@ function loaded(){
     // not just in Web's OSK.
     // TODO: consider using the retrieved stub to get that in future
     $.ajax({
-      url: 'https://api.keyman.com/keyboard/' + keyboardName,
+      url: keymanHosts.api + '/keyboard/' + keyboardName,
       success:function(data) {
         if(typeof data != 'object') return;
 
@@ -203,7 +203,7 @@ function loaded(){
 "	font-family:\""+fontFamily+"\";\n"+
 "	font-style:normal;\n"+
 "	font-weight:normal;\n"+
-"	src:url('https://s.keyman.com/font/deploy/"+fontSource+"') format('"+fontType+"');\n"+
+"	src:url('" + keymanHosts.s + "/font/deploy/"+fontSource+"') format('"+fontType+"');\n"+
 "}\n"+
 ".kmw-key-text { font-family: \""+fontFamily+"\"; }\n"+
 "</style>"