Merge pull request #195 from armanbilge/doc/website

Add page for sbt-typelevel-site plugin

Author: armanbilge

README.md

@@ -8,7 +8,7 @@ sbt-typelevel configures [sbt](https://www.scala-sbt.org/) for developing, testi
 - git-based dynamic versioning
 - Binary-compatibility checking with [MiMa](https://github.com/lightbend/mima), following [early semantic versioning](https://www.scala-lang.org/blog/2021/02/16/preventing-version-conflicts-with-versionscheme.html#early-semver-and-sbt-version-policy)
 - CI publishing of releases and snapshots to Sonatype/Maven
-- CI deployed GitHub pages microsites, generated with [mdoc](https://github.com/scalameta/mdoc/) and [Laika](https://github.com/planet42/laika)
+- CI deployed GitHub pages websites generated with [mdoc](https://github.com/scalameta/mdoc/) and [Laika](https://github.com/planet42/laika)
 - Auto-populated settings for various boilerplate (SCM info, API doc urls, Scala.js sourcemaps, etc.)
 
 ## Get Started

build.sbt

@@ -183,6 +183,7 @@ lazy val docs = project
       "sbt-github-actions" -> url("https://github.com/djspiewak/sbt-github-actions/"),
       "mima" -> url("https://github.com/lightbend/mima"),
       "mdoc" -> url("https://scalameta.org/mdoc/"),
-      "Laika" -> url("https://planet42.github.io/Laika/")
+      "Laika" -> url("https://planet42.github.io/Laika/"),
+      "sbt-unidoc" -> url("https://github.com/sbt/sbt-unidoc")
     )
   )

docs/customization.md

@@ -61,7 +61,7 @@ Instead of using the super-plugins, for finer-grained control you can always add
 - `tlFatalWarningsInCi` (setting): Convert compiler warnings into errors under CI builds (default: true).
 
 ### sbt-typelevel-site
--  `TypelevelSitePlugin`: Sets up an [mdoc](https://scalameta.org/mdoc/)/[Laika](https://planet42.github.io/Laika/)-generated microsite, automatically published to GitHub pages in CI.
+-  `TypelevelSitePlugin`: Sets up an [mdoc](https://scalameta.org/mdoc/)/[Laika](https://planet42.github.io/Laika/)-generated website, automatically published to GitHub pages in CI.
 - `tlSitePublishBranch` (setting): The branch to publish the site from on every push. Set this to `None` if you only want to update the site on tag releases. (default: `main`)
 - `tlSitePublishTags` (setting): Defines whether the site should be published on tag releases. Note on setting this to `true` requires the `tlSitePublishBranch` setting to be set to `None`. (default: `false`)
 - `tlSiteApiUrl` (setting): URL to the API docs. (default: `None`)

docs/directory.conf

@@ -1,5 +1,6 @@
 laika.navigationOrder = [
   index.md
+  site.md
   faq.md
   customization.md
 ]

docs/faq.md

@@ -92,20 +92,6 @@ val root = tlCrossRootProject
 ThisBuild / tlSonatypeUseLegacyHost := false
 ```
 
-## How do I publish a site like this one?
-
-```scala
-// project/plugins.sbt
-addSbtPlugin("org.typelevel" % "sbt-typelevel-site" % "@VERSION@")
-// build.sbt
-ThisBuild / tlSitePublishBranch := Some("main") // deploy docs from this branch
-lazy val docs = project.in(file("site")).enablePlugins(TypelevelSitePlugin)
-```
-
-Place your `.md` files in the `docs/` directory of your project. The site is generated using [mdoc](https://scalameta.org/mdoc/) and [Laika](https://planet42.github.io/Laika/) and published to the `gh-pages` branch on every push to the specified branch. Make sure to enable GitHub pages in your repo settings. 
-
-To preview locally, run `docs/mdoc` and then `docs/laikaPreview`. This should (reasonably quickly) start a webserver you can view on localhost.
-
-To enjoy a tighter edit loop: with `docs/laikaPreview` running, consider firing up another terminal and starting another sbt, then run `docs/mdoc --watch` ([mdoc docs](https://scalameta.org/mdoc/docs/installation.html#live-reload-html-preview-on-file-save)).
-
+## How do I publish a website like this one?
 
+Check out the [**sbt-typelevel-site**](site.md) plugin.

docs/index.md

@@ -8,15 +8,15 @@ sbt-typelevel configures [sbt](https://www.scala-sbt.org/) for developing, testi
 - git-based dynamic versioning
 - Binary-compatibility checking with [MiMa](https://github.com/lightbend/mima), following [early semantic versioning](https://www.scala-lang.org/blog/2021/02/16/preventing-version-conflicts-with-versionscheme.html#early-semver-and-sbt-version-policy)
 - CI publishing of releases and snapshots to Sonatype/Maven
-- CI deployed GitHub pages microsites, generated with [mdoc](https://github.com/scalameta/mdoc/) and [Laika](https://github.com/planet42/laika)
+- CI deployed GitHub pages websites, generated with [mdoc](https://github.com/scalameta/mdoc/) and [Laika](https://github.com/planet42/laika)
 - Auto-populated settings for various boilerplate (SCM info, API doc urls, Scala.js sourcemaps, etc.)
 
 ## Quick start
 
 [![sbt-typelevel Scala version support](https://index.scala-lang.org/typelevel/sbt-typelevel/sbt-typelevel/latest-by-scala-version.svg?targetType=Sbt)](https://index.scala-lang.org/typelevel/sbt-typelevel/sbt-typelevel)
 [![Discord](https://img.shields.io/discord/632277896739946517.svg?label=&logo=discord&logoColor=ffffff&color=404244&labelColor=6A7EC2)](https://discord.gg/D7wY3aH7BQ)
 
-Pick either the `sbt-typelevel` (recommended) or `sbt-typelevel-ci-release` plugin.
+Pick either the **sbt-typelevel** (recommended) or **sbt-typelevel-ci-release** plugin.
 
 #### `project/plugins.sbt`
 

docs/site.md

@@ -0,0 +1,47 @@
+# sbt-typelevel-site
+
+**sbt-typelevel-site** is an optional plugin for generating websites with [mdoc](https://scalameta.org/mdoc/) and [Laika](https://planet42.github.io/Laika/) and deploying to GitHub Pages from CI. You can add it to your build alongside either the  **sbt-typelevel** or **sbt-typelevel-ci-release** plugin.
+
+## Quick start
+
+#### `project/plugins.sbt`
+
+```scala
+addSbtPlugin("org.typelevel" % "sbt-typelevel-site" % "@VERSION@")
+```
+
+#### `build.sbt`
+
+```scala
+// publish website from this branch
+ThisBuild / tlSitePublishBranch := Some("main")
+
+lazy val docs = project.in(file("site")).enablePlugins(TypelevelSitePlugin)
+```
+
+Place your `.md` files in the `docs/` directory of your project. To preview locally, run `docs/tlSitePreview`. This will start a preview server at http://localhost:4242.
+
+The site is generated using [mdoc](https://scalameta.org/mdoc/) and [Laika](https://planet42.github.io/Laika/) and published to the `gh-pages` branch on every push to the specified branch. Make sure to enable GitHub Pages in your repository settings.
+
+### How can I include my project version on the website?
+
+**sbt-typelevel-site** automatically adds `VERSION` and `SNAPSHOT_VERSION` to the `mdocVariables` setting which can be used with [variable injection](https://scalameta.org/mdoc/docs/why.html#variable-injection).
+
+For example, the sbt-typelevel `VERSION` is `@VERSION@` and `SNAPSHOT_VERSION` is `@SNAPSHOT_VERSION@`.
+
+### How can I publish "unidoc" API docs?
+
+If you generate your API documentation with [sbt-unidoc](https://github.com/sbt/sbt-unidoc), you can use the `TypelevelUnidocPlugin` to publish a Scaladoc-only artifact to Sonatype/Maven alongside your library artifacts. This makes it possible to browse your unidocs at [javadoc.io](https://www.javadoc.io/); for example, the sbt-typelevel [API docs](@API_URL@) are published like this.
+
+```scala
+lazy val unidoc = project
+  .in(file("unidoc"))
+  .enablePlugins(TypelevelUnidocPlugin) // also enables the ScalaUnidocPlugin
+  .settings(
+    name := "woozle-docs"
+  )
+```
+
+### How can I customize my website's appearance?
+
+We refer you to the comprehensive [Laika manual](https://planet42.github.io/Laika/index.html) and specifically the [`laikaTheme` setting](https://planet42.github.io/Laika/0.18/02-running-laika/01-sbt-plugin.html#laikatheme-setting).

site/src/main/scala/org/typelevel/sbt/TypelevelSitePlugin.scala

@@ -106,10 +106,14 @@ object TypelevelSitePlugin extends AutoPlugin {
     tlSitePreview := previewTask.value,
     Laika / sourceDirectories := Seq(mdocOut.value),
     laikaTheme := tlSiteHeliumConfig.value.build.extend(tlSiteHeliumExtensions.value),
-    mdocVariables ++= Map(
-      "VERSION" -> currentRelease.value.getOrElse(version.value),
-      "SNAPSHOT_VERSION" -> version.value
-    ),
+    mdocVariables := {
+      mdocVariables.value ++
+        Map(
+          "VERSION" -> currentRelease.value.getOrElse(version.value),
+          "SNAPSHOT_VERSION" -> version.value
+        ) ++
+        tlSiteApiUrl.value.map("API_URL" -> _.toString).toMap
+    },
     tlSiteHeliumExtensions := TypelevelHeliumExtensions(
       licenses.value.headOption,
       tlSiteRelatedProjects.value