Add more documentation

src/main/resources/creativescala/content/README.md

@@ -1,6 +1,6 @@
 # Creative Scala Theme
 
-This is a demonstration of the Creative Scala theme. It is designed to show off the features of the theme, and serve as an example to speed up development.
+This is both a demonstration of the Creative Scala theme and documentation for it.
 
 
 ## Installation
@@ -15,30 +15,38 @@ replacing `<version>` with the most recent version. Then, in where you configure
 
 ```scala
 laikaTheme := CreativeScalaTheme.empty
-  .addJs(laika.ast.Path.Root / "xterm.js")
   .addJs(laika.ast.Path.Root / "main.js")
-  .addCss(laika.ast.Path.Root / "xterm.css")
+  .addCss(laika.ast.Path.Root / "main.css")
   .build
 ```
 
 replacing `addJs` etc. with appropriate values for your project. You can remove these calls if you don't have any custom configuration.
 
 
-## Creating this Example
+## Development
 
-From sbt, simply use the `run` command:
+Here are a few tips for development of this theme.
+
+
+### Creating this Example
+
+From sbt, simply use the `run` command from within sbt:
 
 ```bash
-sbt run
+run
 ```
 
 This will generate output in the `target` directory. Open `target/index.html` in a web browser to see the rendered output.
 
 
-## Developing Content
+### Developing Content
 
-You'll want to have Tailwind generating CSS whenever a change is made to `src/main/css/creative-scala.css`:
+When working on this theme you'll be spending most of your time working on the CSS in `src/main/css/creative-scala.css` and the template in `src/main/resources/creativescala/tempaltes/default.html.html`. The following sbt command will rebuild the CSS and then regenerate this site.
 
 ```bash
 sbt css
 ```
+
+The CSS uses [Tailwind CSS][tailwind]. You will need to have the `tailwindcss` executable installed as described in the Tailwind CSS documentation.
+
+[tailwind]: https://tailwindcss.com/docs

src/main/resources/creativescala/content/configuration/README.md

@@ -1 +1,6 @@
 # Configuration
+
+This theme allows some limited configuration:
+
+- [changing the links in the top navigation bar](top-nav.md); and
+- [adding additional CSS and JS](css-js.md)

src/main/resources/creativescala/content/configuration/css-js.md

@@ -1,2 +1,10 @@
 # CSS and Javascript
 
+You can add your own CSS and Javascript files to your site using the `addCss` and `addJs` methods on `CreativeScalaTheme`. These takes instances of `laika.ast.Path`. Here's an example in use:
+
+```scala
+laikaTheme := CreativeScalaTheme.empty
+  .addJs(laika.ast.Path.Root / "main.js")
+  .addCss(laika.ast.Path.Root / "main.css")
+  .build
+```

src/main/resources/creativescala/content/configuration/top-nav.md

@@ -1,2 +1,28 @@
 # Top Navigation
 
+You can customize the links in the top navigation bar to link to your own community, API, and so on. To do this you call methods on an instance of `CreativeSCalaTheme`. This will usually be in your `build.sbt` where you'll have a line something like
+
+```scala
+laikaTheme := CreativeScalaTheme.empty
+  .build
+```
+
+The instance of `CreativeScalaTheme`, created by the code `CreativeScalaTheme.empty`, has the following methods:
+
+- `withHome`, which allows you to set the link in the center of the top bar (which is "Creative Scala Theme" above). It is supposed to link to the home page of your documentation site and defaults to the root of your documentation.
+- `withCommunity`, which allows you to set the link to your community (e.g. a group chat service like Discord).
+- `withApi`, which allows you to link to your API documentation. For most Scala projects this will be `javadoc.io`.
+- `withSource`, which allows you to specify the link to your source code, often on Github.
+
+All of these methods take a value of `SingleTargetLink`, which is taken from Laika's Helium theme. You'll need the import below to use it.
+
+```scala
+import laika.helium.config.SingleTargetLink
+```
+
+This allows you specify links in a variety of formats, including images and icons. Below are examples of creating a text link to another page in your Laika documentation, and a text link to an external site.
+
+```scala
+TextLink.internal(Path.Root / "README.md", "Home"),
+TextLink.external("https://discord.gg", "Community"),
+```

src/main/resources/creativescala/content/directives/README.md

@@ -0,0 +1,5 @@
+# Directives
+
+This theme comes with a number of directives you can use to add features to your documentation.
+
+*TO BE CONTINUED*

src/main/resources/creativescala/content/directory.conf

@@ -1,5 +1,6 @@
 laika.navigationOrder = [
   README.md
+  features.md
   configuration
-  responsive.md
+  directives
 ]

src/main/resources/creativescala/content/features.md

@@ -0,0 +1,12 @@
+# Features
+
+Here is a brief overview of the features of this template:
+
+- It has some basic [responsive][responsive] features, meaning it adapts to changing screen sizes. On wide screens you'll have a table of contents for the site on the left, and on the right a table of contents for the page. On narrow screens these both disappear and are replaced by a table of contents that is accessed from the top bar.
+
+- It allows [configuration](/configuration/README.md) of the links on the top bar and adding additional Javascript and CSS files. Note that this theme is *not* designed to allow for heavy customization. If you want to change the fonts, color scheme, or make more radical changes, you'll want to fork the theme.
+
+- It provides a range of [directives](/directives/README.md) that I've found useful in documenting my projects.
+
+
+[responsive]: https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design