Skip to content

Commit

Permalink
Updates docs
Browse files Browse the repository at this point in the history
  • Loading branch information
juanpedromoreno committed Dec 23, 2020
1 parent c126f28 commit 743aabd
Show file tree
Hide file tree
Showing 9 changed files with 14 additions and 34 deletions.
2 changes: 1 addition & 1 deletion microsite/docs/docs/build-the-microsite.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Once you have written your documents, you can build the microsite running this s
sbt> makeMicrosite
```

Internally, it'll sequentially run other tasks including its own, [`tut`](https://github.com/tpolecat/tut) or [`mdoc`](https://scalameta.org/mdoc/), and `makeSite` ([sbt-site](https://github.com/sbt/sbt-site)) tasks.
Internally, it'll sequentially run other tasks including its own, [`mdoc`](https://scalameta.org/mdoc/), and `makeSite` ([sbt-site](https://github.com/sbt/sbt-site)) tasks.


# Multiversion support
Expand Down
5 changes: 1 addition & 4 deletions microsite/docs/docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,4 @@ enablePlugins(MicrositesPlugin)

# Write your documentation `.md` files

Your docs can be placed wherever you want in your project since there are sbt settings to point to the sources of your microsite, however the plugin expects to find the sources where both [**tut**](https://github.com/tpolecat/tut) and [**mdoc**](https://github.com/scalameta/mdoc) have defined by default. They are:

- Tut: `src/main/tut/`
- mdoc: `docs/`
Your docs can be placed wherever you want in your project since there are sbt settings to point to the sources of your microsite, however the plugin expects to find the sources where [**mdoc**](https://github.com/scalameta/mdoc) have defined by default (`docs/`).
1 change: 0 additions & 1 deletion microsite/docs/docs/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,6 @@ The plugin provides basic free styles, css, and image resources by default. Ever

In order to create microsites, this plugin directly uses the following plugins and libraries:

* [tut-plugin](https://github.com/tpolecat/tut)
* [sbt-mdoc](https://github.com/scalameta/mdoc)
* [sbt-site](https://github.com/sbt/sbt-site)
* [sbt-ghpages](https://github.com/sbt/sbt-ghpages)
Expand Down
2 changes: 1 addition & 1 deletion microsite/docs/docs/layouts.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ To be able to access the documentation, you have to configure `micrositeDocument

In order to change the default label description for the `micrositeDocumentationUrl` (the default value is `Documentation`), you have to change the `micrositeDocumentationLabelDescription`.

As an example, you can look at the sbt-microsites documentation at [GitHub](https://github.com/47deg/sbt-microsites/tree/master/docs/src/main/tut). We have several documentation files:
As an example, you can look at the sbt-microsites documentation at [GitHub](https://github.com/47degrees/sbt-microsites/tree/master/microsite/docs). We have several documentation files:

- `build-the-microsite.md`
- `customize.md`
Expand Down
13 changes: 3 additions & 10 deletions microsite/docs/docs/settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -260,7 +260,7 @@ micrositeStaticDirectory := (resourceDirectory in Compile).value / "site" / "mys

The directory will be copied as-is, but no process will be applied to any file on it. So the responsibility of loading/linking/using them on a layout is yours. Also, see the `includeFilter in makeSite` config setting for the allowed file types that will be copied.

- `micrositeExtraMdFiles`: This setting can be handy if you want to include additional markdown files in your site, and these files are not located in the same place in your `mdoc` or `tut` directory. By default, the setting is set up as an empty map. You can override it in this way:
- `micrositeExtraMdFiles`: This setting can be handy if you want to include additional markdown files in your site, and these files are not located in the same place in your `mdoc` directory. By default, the setting is set up as an empty map. You can override it in this way:

```scala
micrositeExtraMdFiles := Map(
Expand All @@ -278,7 +278,7 @@ micrositeExtraMdFiles := Map(

Each file (the map key) can be related to a specific configuration through the `ExtraMdFileConfig` case class. This class allows you to specify three additional configurations:

1. The target file name. The plugin will copy the file, and it will put it in tut directory each time you build the microsite. Therefore, you might want to include this auto-copied file in the list of ignored files at the `.gitignore` file.
1. The target file name. The plugin will copy the file, and it will put it in mdoc directory each time you build the microsite. Therefore, you might want to include this auto-copied file in the list of ignored files at the `.gitignore` file.
2. Jekyll `layout` property.
3. Other custom Jekyll properties that you might want to include in your document. A good point to highlight here is that through the `permalink` property you can control the place where `Jekyll` is going to move your extra file. The value of this property prevails over the folder where the file is copied.

Expand Down Expand Up @@ -367,16 +367,9 @@ repository URL, and should include the dynamic property `{% raw %}{{page.path}}{
compiles the site. **The strings are passed in unsanitized to the templating engine.**

```scala
{% raw %}micrositeEditButton := Some(MicrositeEditButton("Improve this Page", "/edit/master/docs/src/main/tut/{{ page.path }}")){% endraw %}
{% raw %}micrositeEditButton := Some(MicrositeEditButton("Improve this Page", "/edit/master/docs/{{ page.path }}")){% endraw %}
```

- `micrositeCompilingDocsTool`: Choose between compiling code snippets with [**tut**](https://github.com/tpolecat/tut) or [**mdoc**](https://github.com/scalameta/mdoc). By default, it's set to `WithMdoc` since the sbt-microsites 1.0.0 release. But you could use `WithTut` if you want to preserve the compatibility with previous versions of your markdown files.

```scala
micrositeCompilingDocsTool := WithMdoc
```
If you are interested in learning where to place the markdown files according to the compilation tool chosen, please take a look at the [Typechecked Snippets]({% link docs/typechecked-snippets.md %}) section.

- `includeFilter in makeSite`: Restrict the type of files that are included during the microsite build. The default value is `"*.html" | "*.css" | "*.png" | "*.jpg" | "*.jpeg" | "*.gif" | "*.js" | "*.swf" | "*.md" | "*.webm" | "*.ico" | "CNAME" | "*.yml" | "*.svg" | "*.json"` but you can override it like this:

```scala
Expand Down
19 changes: 2 additions & 17 deletions microsite/docs/docs/typechecked-snippets.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,33 +6,18 @@ permalink: docs/typechecked-snippets/

# Typechecked Snippets

As has been mentioned a couple of times throughout this tutorial, this plugin supports the compilation of Scala code written in markdown files. This process is now being delegated on two different sbt plugins: [**tut**](https://github.com/tpolecat/tut) and [**mdoc**](https://github.com/scalameta/mdoc).

## Tut

[tut](https://github.com/tpolecat/tut) has been deprecated, please switch to mdoc (see next section). If for some reason you want to keep using it, here there are some recommendations:

- Set this property accordingly: `micrositeCompilingDocsTool := WithTut`.
- Add your markdown files in this path by default: `src/main/tut/`.
- If you want to place your documments in a different path, just set the sbt property `tutSourceDirectory := your-path` being _your-path_ a `SettingKey[File]`.
- Mark the snippets that you want to compile, following this convention: **_```tut_** or any of its [modifiers](https://tpolecat.github.io/tut/modifiers.html)

As has been mentioned a couple of times throughout this tutorial, this plugin supports the compilation of Scala code written in markdown files. This process is now being delegated on [**mdoc**](https://github.com/scalameta/mdoc).

## mdoc

`mdoc` is the option by default, so no special action is required from your side. See the scalameta site for more information [here](https://scalameta.org/mdoc/). Here is some advice for using this in your microsite:

- Add your markdown files in this path by default: `docs/`.
- By default, the setting `micrositeCompilingDocsTool` will be `WithMdoc`, so no action would be required.
- If you want to place your documents in a different path, just set the sbt property `mdocIn := your-path` being _your-path_ a `SettingKey[File]`.
- Mark the snippets that you want to compile, following this convention: **_```scala mdoc_** or any of its [modifiers](https://scalameta.org/mdoc/docs/modifiers.html)

## Migrating from tut to mdoc

You can migrate your microsite from _tut_ to _mdoc_ in 3 smooth steps:

- Set this property accordingly: `micrositeCompilingDocsTool := WithMdoc`
- Set the property `mdocIn := tutSourceDirectory`, thus we are setting the source for mdoc as it used to be for tut.
- Replace **_tut_** with **_mdoc_** in the snippets modifiers following this [migration guide](https://scalameta.org/mdoc/docs/tut.html).
If your project is still based on `tut`, you can migrate it from _tut_ to _mdoc_ can follow this [migration guide](https://scalameta.org/mdoc/docs/tut.html).

There is also a [script](https://github.com/scalameta/mdoc/blob/5c732bc48eb88b8a416e5c61e945eac6d410b27b/bin/migrate-tut.sh) that does the replacement for you.
3 changes: 3 additions & 0 deletions src/sbt-test/microsites/extra-md-files/docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Overview

README file of the project, located in the project's root.
3 changes: 3 additions & 0 deletions src/sbt-test/microsites/microsites-tasks/docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Overview

README file of the project, located in the project's root.

0 comments on commit 743aabd

Please sign in to comment.