Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Implement feature links #417

Merged
merged 3 commits into from
Feb 4, 2020
Merged

Implement feature links #417

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c9e35f3
Implement feature links
AntonioMateoGomez Jan 29, 2020
ad97521
Merge branch 'master' into paolo-391-feature-links
AntonioMateoGomez Feb 4, 2020
61e8503
Update layouts.md
jkmcclellan Feb 4, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 12 additions & 11 deletions docs/docs/docs/layouts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,15 @@ permalink: docs/layouts/
Currently, the sbt-microsites plugin includes five different layouts:

- There are two different options for the home section:
- `home`: The landing page, the public face of your library or project.
- `homeFeatures`: Another option for the landing page, choosing this option you could highlight some special features you consider your library offers. (This layout is not available for the classic pattern style)
- `docs` (Optional): The page where the documentation for your library should be included. Most likely, you are seeing the `Documentation` page of this repo right now. It's optional, depending on the `micrositeDocumentationUrl` setting. Take a look at the [Configuring the Microsite]({% link docs/settings.md %}) section for an in-depth explanation.
- `home`: The landing page--the public face of your library or project.
- `homeFeatures`: Another option for the landing page. Choosing this option, you could highlight some of the special features your library offers. (This layout is not available for the classic pattern style)
- `docs` (Optional): The page where the documentation for your library should be included. You are most likely seeing the `Documentation` page of this repo right now. It's optional, depending on the `micrositeDocumentationUrl` setting. Take a look at the [Configuring the Microsite]({% link docs/settings.md %}) section for an in-depth explanation.
- `page` (Optional): Similar to `home`, but reducing the jumbotron layer and taking into account the submenu (jumbotron and other concepts related to style are explained in the [Customize]({% link docs/customize.md %}) section).
- Menu Partial: This abstract layout reads all the files in your project that fit a set of requirements, and sets up a menu under the jumbotron image. We'll see more details on this later.

## Home Layout

Usually, the `home` layout is related to the `index.md` file. In this document, you can put all the markdown content that's related to the landing page.
The `home` layout is usually related to the `index.md` file. In this document, you can put all the markdown content that's related to the landing page.

For instance:

Expand All @@ -34,12 +34,12 @@ technologies:
```

The technology list is optional. These three technologies will be shown as a sub-footer in your home page. These technologies are identified for the set of keys (`first`, `second`, `third`). You can specify to include all of them or none of them. There are no other choices at this time.
This list is only available in the `pattern` theme, but for the `light` theme we have included the `homeFeatures` layout where you can highlight similar characteristics of your library.
This list is only available in the `pattern` theme, but, for the `light` theme, we have included the `homeFeatures` layout where you can highlight similar characteristics of your library.


## HomeFeatures Layout

As the `home` layout `homeFeatures` is related to the `index.md` file.
Like the `home` layout, `homeFeatures` is related to the `index.md` file.
This layout is designed to show a main title beside a big logo, and then a series of features that can be highlighted from the library.

For instance:
Expand All @@ -48,15 +48,16 @@ For instance:
---
layout: homeFeatures
features:
- first: ["Patterns", "Solutions to recurrent problems, in a purely Functional Programming manner."]
- second: ["Typeclasses", "Enable ad-hoc polymorphism with protocols like Functor, Applicative, Monad and many others."]
- third: ["Data Types", "Take advantage of numerous data types based on algebraic properties."]
- first: ["Patterns", "Solutions to recurrent problems, in a purely Functional Programming manner.", "patterns"]
- second: ["Typeclasses", "Enable ad-hoc polymorphism with protocols like Functor, Applicative, Monad, and many others.", "typeclasses"]
- third: ["Data Types", "Take advantage of numerous data types based on algebraic properties.", "datatypes"]
---
```

Basically this is all you´ll need to add to your `index.md` file using the `homeFeatures` layout.
You can add up to three different features and sbt-microsites will dispose them after the masthead layer, every feature will be accompained by an icon that can be overridden as explained in the [Customize]({% link docs/customize.md %}) section.
This is basically all you´ll need to add to your `index.md` file using the `homeFeatures` layout.
You can add up to three different features, and sbt-microsites will dispose them after the masthead layer. Every feature will be accompained by an icon that can be overridden, as explained in the [Customize]({% link docs/customize.md %}) section.
These features are identified for the set of keys (`first`, `second`, `third`).
The last value of each feature is optional and will be used to set the link to the docs section. For instance, the first feature in the example: `patterns`, this will serve to compose `docs/patterns` link to the docs section.

## Docs Layout

Expand Down
4 changes: 2 additions & 2 deletions docs/docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: homeFeatures
features:
- first: ["Configuration", "sbt-microsites facilitates the creation of fancy microsites for your projects, with minimal tweaks"]
- second: ["Customize", "sbt-microsites provides a considerable scope for improvement and customization in terms of images and styles"]
- first: ["Configuration", "sbt-microsites facilitates the creation of fancy microsites for your projects, with minimal tweaks", "settings"]
- second: ["Customize", "sbt-microsites provides a considerable scope for improvement and customization in terms of images and styles", "customize"]
- third: ["Documentation", "Writing documentation for your own microsites is fast and easy, so you don't have to deal with details"]
---
110 changes: 71 additions & 39 deletions src/main/scala/microsites/MicrositeKeys.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright 2016-2019 47 Degrees, LLC. <http://www.47deg.com>
* Copyright 2016-2020 47 Degrees, LLC. <http://www.47deg.com>
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
Expand Down Expand Up @@ -73,17 +73,21 @@ trait MicrositeKeys {
taskKey[Unit]("Dynamic task that will evaluate makeTut or makeMdoc depending on setting")
val createMicrositeVersions: TaskKey[Unit] =
taskKey[Unit](
"Task to create the different microsites going through the list specified in the settings")
"Task to create the different microsites going through the list specified in the settings"
)
val moveMicrositeVersions: TaskKey[Unit] =
taskKey[Unit](
"Task to move the different microsites to their final publishing directory destination")
"Task to move the different microsites to their final publishing directory destination"
)
val makeVersionsJson: TaskKey[Unit] =
taskKey[Unit](
"Task that will create the expected formattted JSON with the versions specified in the settings")
"Task that will create the expected formattted JSON with the versions specified in the settings"
)
val makeVersionedMicrosite: TaskKey[Unit] =
taskKey[Unit]("Task similar to makeMicrosite, adding a version selector")
val makeMultiversionMicrosite: TaskKey[Unit] = taskKey[Unit](
"Main task to build a microsite, including version selector, and microsite different versions")
"Main task to build a microsite, including version selector, and microsite different versions"
)
val pushMicrosite: TaskKey[Unit] =
taskKey[Unit]("Task to just push files up.")
val publishMicrosite: TaskKey[Unit] =
Expand Down Expand Up @@ -118,52 +122,69 @@ trait MicrositeKeys {
val micrositeConfigYaml: SettingKey[ConfigYml] =
settingKey[ConfigYml]("Microsite _config.yml file configuration.")
val micrositeImgDirectory: SettingKey[File] = settingKey[File](
"Optional. Microsite images directory. By default, it'll be the resourcesDirectory + '/microsite/img'")
"Optional. Microsite images directory. By default, it'll be the resourcesDirectory + '/microsite/img'"
)
val micrositeCssDirectory: SettingKey[File] = settingKey[File](
"Optional. Microsite CSS directory. By default, it'll be the resourcesDirectory + '/microsite/css'")
"Optional. Microsite CSS directory. By default, it'll be the resourcesDirectory + '/microsite/css'"
)
val micrositeSassDirectory: SettingKey[File] = settingKey[File](
"Optional. Microsite SASS directory. By default, it'll be the resourcesDirectory + '/microsite/sass'")
"Optional. Microsite SASS directory. By default, it'll be the resourcesDirectory + '/microsite/sass'"
)
val micrositeJsDirectory: SettingKey[File] = settingKey[File](
"Optional. Microsite Javascript directory. By default, it'll be the resourcesDirectory + '/microsite/js'")
"Optional. Microsite Javascript directory. By default, it'll be the resourcesDirectory + '/microsite/js'"
)
val micrositeCDNDirectives: SettingKey[CdnDirectives] = settingKey[CdnDirectives](
"Optional. Microsite CDN directives lists (for css and js imports). By default, both lists are empty.")
"Optional. Microsite CDN directives lists (for css and js imports). By default, both lists are empty."
)
val micrositeExternalLayoutsDirectory: SettingKey[File] = settingKey[File](
"Optional. Microsite external layouts directory. By default, it'll be the resourcesDirectory + '/microsite/layout'")
"Optional. Microsite external layouts directory. By default, it'll be the resourcesDirectory + '/microsite/layout'"
)
val micrositeExternalIncludesDirectory: SettingKey[File] = settingKey[File](
"Optional. Microsite external includes (partial layouts) directory. By default, it'll be the resourcesDirectory + '/microsite/includes'")
"Optional. Microsite external includes (partial layouts) directory. By default, it'll be the resourcesDirectory + '/microsite/includes'"
)
val micrositeDataDirectory: SettingKey[File] = settingKey[File](
"Optional. Microsite Data directory, useful to define the microsite data files " +
"(https://jekyllrb.com/docs/datafiles/). By default, it'll be the resourcesDirectory + '/microsite/data'")
"(https://jekyllrb.com/docs/datafiles/). By default, it'll be the resourcesDirectory + '/microsite/data'"
)
val micrositeStaticDirectory: SettingKey[File] = settingKey[File](
"Optional. Microsite static files directory. By default, it'll be the resourcesDirectory + '/microsite/static'")
"Optional. Microsite static files directory. By default, it'll be the resourcesDirectory + '/microsite/static'"
)
val micrositeExtraMdFiles: SettingKey[Map[File, ExtraMdFileConfig]] =
settingKey[Map[File, ExtraMdFileConfig]](
"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.")
"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."
)
val micrositeExtraMdFilesOutput: SettingKey[File] = settingKey[File](
"Optional. Microsite output location for extra-md files. Default is resourceManaged + '/jekyll/extra_md'")
"Optional. Microsite output location for extra-md files. Default is resourceManaged + '/jekyll/extra_md'"
)
val micrositePluginsDirectory: SettingKey[File] = settingKey[File](
"Optional. Microsite Plugins directory. By default, it'll be the resourcesDirectory + '/microsite/plugins'")
"Optional. Microsite Plugins directory. By default, it'll be the resourcesDirectory + '/microsite/plugins'"
)
val micrositePalette: SettingKey[Map[String, String]] =
settingKey[Map[String, String]]("Microsite palette")
val micrositeFavicons: SettingKey[Seq[MicrositeFavicon]] = settingKey[Seq[MicrositeFavicon]](
"Optional. List of filenames and sizes for the PNG/ICO files to be used as favicon for the generated site, located in '/microsite/img'. The sizes should be described with a string (i.e.: \"16x16\"). By default, favicons with different sizes will be generated from the navbar_brand2x.jpg file.")
"Optional. List of filenames and sizes for the PNG/ICO files to be used as favicon for the generated site, located in '/microsite/img'. The sizes should be described with a string (i.e.: \"16x16\"). By default, favicons with different sizes will be generated from the navbar_brand2x.jpg file."
)
val micrositeGithubOwner: SettingKey[String] = settingKey[String]("Microsite Github owner")
val micrositeGithubRepo: SettingKey[String] = settingKey[String]("Microsite Github repo")
val micrositeGithubToken: SettingKey[Option[String]] =
settingKey[Option[String]]("Microsite Github token for pushing the microsite")
val micrositeGithubLinks: SettingKey[Boolean] = settingKey[Boolean](
"Optional. Includes Github links (forks, stars) in the layout. Enabled by default.")
"Optional. Includes Github links (forks, stars) in the layout. Enabled by default."
)
val micrositeGitHostingService: SettingKey[GitHostingService] =
settingKey[GitHostingService]("Service used for git hosting. By default, it'll be GitHub.")
val micrositeGitHostingUrl: SettingKey[String] = settingKey[String](
"In the case where your project isn't hosted on Github, use this setting to point users to git host (e.g. 'https://internal.gitlab.com/<user>/<project>').")
"In the case where your project isn't hosted on Github, use this setting to point users to git host (e.g. 'https://internal.gitlab.com/<user>/<project>')."
)
val micrositePushSiteWith: SettingKey[PushWith] =
settingKey[PushWith](
"Determines what will be chosen for pushing the site. The options are sbt-ghpages plugin and github4s library.")
"Determines what will be chosen for pushing the site. The options are sbt-ghpages plugin and github4s library."
)

val micrositeAnalyticsToken: SettingKey[String] =
settingKey[String](
"Optional. Add your property id of Google Analytics to add a Google Analytics tracker")
"Optional. Add your property id of Google Analytics to add a Google Analytics tracker"
)
val micrositeGitterChannel: SettingKey[Boolean] = settingKey[Boolean](
"Optional. Includes Gitter sidecar Chat functionality. Enabled by default."
)
Expand All @@ -188,7 +209,8 @@ trait MicrositeKeys {
settingKey[CompilingDocsTool]("Choose between compiling code snippets with tut or mdoc")

val micrositeTheme: SettingKey[String] = settingKey[String](
"Optional. 'light' by default. Set it to 'pattern' to generate the pattern theme design.")
"Optional. 'light' by default. Set it to 'pattern' to generate the pattern theme design."
)

val micrositeVersionList: SettingKey[Seq[String]] =
settingKey[Seq[String]]("Optional. Microsite available versions")
Expand Down Expand Up @@ -227,7 +249,8 @@ trait MicrositeAutoImportSettings extends MicrositeKeys {
sourceDir: String,
targetDir: String,
baseUrl: String,
version: String): Unit = {
version: String
): Unit = {
val newBaseUrl =
if (version.nonEmpty) s"$baseUrl/$version" else baseUrl
val pluginName = "microsites.MicrositesPlugin"
Expand All @@ -236,7 +259,8 @@ trait MicrositeAutoImportSettings extends MicrositeKeys {
case Some(projects) => {
List(
"sbt",
s"""clean; project ${projects(0)}; set micrositeBaseUrl := "$newBaseUrl"; makeMicrosite""").!
s"""clean; project ${projects(0)}; set micrositeBaseUrl := "$newBaseUrl"; makeMicrosite"""
).!
Files.move(
Paths.get(sourceDir),
Paths.get(s"$targetDir/$version"),
Expand Down Expand Up @@ -285,14 +309,15 @@ trait MicrositeAutoImportSettings extends MicrositeKeys {
"sass" -> Map(
"load_paths" -> List("_sass", "_sass_custom"),
"style" -> "compressed",
"sourcemap" -> "never",
"sourcemap" -> "never"
),
"collections" -> Map("tut" -> Map("output" -> true))
)

val userCustomVariables = micrositeConfigYaml.value
val configWithAllCustomVariables = userCustomVariables.copy(
yamlCustomProperties = defaultYamlCustomVariables ++ userCustomVariables.yamlCustomProperties)
yamlCustomProperties = defaultYamlCustomVariables ++ userCustomVariables.yamlCustomProperties
)

new MicrositeHelper(
MicrositeSettings(
Expand Down Expand Up @@ -359,12 +384,13 @@ trait MicrositeAutoImportSettings extends MicrositeKeys {
multiversionSettings = MicrositeMultiversionSettings(
micrositeVersionList.value
)
))
)
)
}

lazy val micrositeTasksSettings = Seq(
microsite := micrositeHelper.value.createResources(
resourceManagedDir = (resourceManaged in Compile).value),
microsite := micrositeHelper.value
.createResources(resourceManagedDir = (resourceManaged in Compile).value),
micrositeMakeExtraMdFiles := micrositeHelper.value.buildAdditionalMd(),
micrositeTutExtraMdFiles := {
val r = (runner in Tut).value
Expand Down Expand Up @@ -403,7 +429,8 @@ trait MicrositeAutoImportSettings extends MicrositeKeys {

val versionList = generateVersionList(
(currentBranchTag :: micrositeVersionList.value.toList),
currentBranchTag)
currentBranchTag
)

createVersionsJson(targetDir, versionList)
},
Expand All @@ -420,28 +447,29 @@ trait MicrositeAutoImportSettings extends MicrositeKeys {
scala.reflect.io.Directory(new File(genDocsDir)).deleteRecursively()
createDir(genDocsDir)

micrositeVersionList.value.foreach(tag => {
micrositeVersionList.value.foreach { tag =>
s"git checkout -f $tag".!
createMicrositeVersion(
publishingDir.getAbsolutePath,
genDocsDir,
micrositeBaseUrl.value,
tag)
})
tag
)
}

s"git checkout -f $currentBranchTag".!
},
moveMicrositeVersions := {
val publishingDir = (target in makeSite).value
val genDocsDir = ".sbt-versioned-docs"

micrositeVersionList.value.foreach(tag => {
micrositeVersionList.value.foreach { tag =>
Files.move(
Paths.get(s"$genDocsDir/$tag"),
Paths.get(s"${publishingDir.getPath()}/$tag"),
StandardCopyOption.REPLACE_EXISTING
)
})
}
},
makeVersionedMicrosite := {
Def.sequential(microsite, makeVersionsJson, makeDocs, makeSite)
Expand Down Expand Up @@ -488,13 +516,17 @@ trait MicrositeAutoImportSettings extends MicrositeKeys {
case (GitHub4s.name, GitHub.name) =>
Def.task(
log.error(
s"You must provide a GitHub token through the `micrositeGithubToken` setting for pushing with github4s")
s"You must provide a GitHub token through the `micrositeGithubToken` setting for pushing with github4s"
)
)
case (GitHub4s.name, hosting) =>
Def.task(log.warn(s"github4s doesn't have support for $hosting"))
case _ =>
Def.task(log.error(
s"""Unexpected match case (pushSiteWith, gitHosting) = ("${pushSiteWith.name}", "${gitHosting.name}")"""))
Def.task(
log.error(
s"""Unexpected match case (pushSiteWith, gitHosting) = ("${pushSiteWith.name}", "${gitHosting.name}")"""
)
)
}
}.value,
publishMicrosite := {
Expand Down
Loading