You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: microsite/docs/docs/build-the-microsite.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ Once you have written your documents, you can build the microsite running this s
12
12
sbt> makeMicrosite
13
13
```
14
14
15
-
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.
15
+
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.
Copy file name to clipboardExpand all lines: microsite/docs/docs/getting-started.md
+1-4Lines changed: 1 addition & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -57,7 +57,4 @@ enablePlugins(MicrositesPlugin)
57
57
58
58
# Write your documentation `.md` files
59
59
60
-
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:
61
-
62
-
- Tut: `src/main/tut/`
63
-
- mdoc: `docs/`
60
+
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/`).
Copy file name to clipboardExpand all lines: microsite/docs/docs/layouts.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -67,7 +67,7 @@ To be able to access the documentation, you have to configure `micrositeDocument
67
67
68
68
In order to change the default label description for the `micrositeDocumentationUrl` (the default value is `Documentation`), you have to change the `micrositeDocumentationLabelDescription`.
69
69
70
-
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:
70
+
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:
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.
262
262
263
-
-`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:
263
+
-`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:
264
264
265
265
```scala
266
266
micrositeExtraMdFiles :=Map(
@@ -278,7 +278,7 @@ micrositeExtraMdFiles := Map(
278
278
279
279
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:
280
280
281
-
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.
281
+
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.
282
282
2. Jekyll `layout` property.
283
283
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.
284
284
@@ -367,16 +367,9 @@ repository URL, and should include the dynamic property `{% raw %}{{page.path}}{
367
367
compiles the site. **The strings are passed in unsanitized to the templating engine.**
368
368
369
369
```scala
370
-
{% raw %}micrositeEditButton :=Some(MicrositeEditButton("Improve this Page", "/edit/master/docs/src/main/tut/{{ page.path }}")){% endraw %}
370
+
{% raw %}micrositeEditButton :=Some(MicrositeEditButton("Improve this Page", "/edit/master/docs/{{ page.path }}")){% endraw %}
371
371
```
372
372
373
-
-`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.
374
-
375
-
```scala
376
-
micrositeCompilingDocsTool :=WithMdoc
377
-
```
378
-
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.
379
-
380
373
-`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:
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).
10
-
11
-
## Tut
12
-
13
-
[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:
14
-
15
-
- Set this property accordingly: `micrositeCompilingDocsTool := WithTut`.
16
-
- Add your markdown files in this path by default: `src/main/tut/`.
17
-
- 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]`.
18
-
- Mark the snippets that you want to compile, following this convention: **_```tut_** or any of its [modifiers](https://tpolecat.github.io/tut/modifiers.html)
19
-
9
+
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).
20
10
21
11
## mdoc
22
12
23
13
`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:
24
14
25
15
- Add your markdown files in this path by default: `docs/`.
26
-
- By default, the setting `micrositeCompilingDocsTool` will be `WithMdoc`, so no action would be required.
27
16
- 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]`.
28
17
- 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)
29
18
30
19
## Migrating from tut to mdoc
31
20
32
-
You can migrate your microsite from _tut_ to _mdoc_ in 3 smooth steps:
33
-
34
-
- Set this property accordingly: `micrositeCompilingDocsTool := WithMdoc`
35
-
- Set the property `mdocIn := tutSourceDirectory`, thus we are setting the source for mdoc as it used to be for tut.
36
-
- Replace **_tut_** with **_mdoc_** in the snippets modifiers following this [migration guide](https://scalameta.org/mdoc/docs/tut.html).
21
+
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).
37
22
38
23
There is also a [script](https://github.com/scalameta/mdoc/blob/5c732bc48eb88b8a416e5c61e945eac6d410b27b/bin/migrate-tut.sh) that does the replacement for you.
"Optional. This key is useful when you want to include automatically markdown documents as a part of your microsite, and these files are located in different places from the tutSourceDirectory. The map key is related with the source file, the map value corresponds with the target relative file path and the document meta-information configuration. By default, the map is empty."
149
+
"Optional. This key is useful when you want to include automatically markdown documents as a part of your microsite, and these files are located in different places. The map key is related with the source file, the map value corresponds with the target relative file path and the document meta-information configuration. By default, the map is empty."
0 commit comments