12 files changed, 330 insertions, 11 deletions
diff --git a/doc-tool/resources/_layouts/api-page.html b/doc-tool/resources/_layouts/api-page.html
index 0e39f9d91..f45a8bab4 100644
--- a/doc-tool/resources/_layouts/api-page.html
+++ b/doc-tool/resources/_layouts/api-page.html
@@ -1,5 +1,5 @@
 ---
-layout: doc
+layout: sidebar
 extraCSS:
     - css/api-page.css
 ---
diff --git a/doc-tool/resources/_layouts/blog.html b/doc-tool/resources/_layouts/blog-page.html
index d7a08414a..b99a16b9c 100644
--- a/doc-tool/resources/_layouts/blog.html
+++ b/doc-tool/resources/_layouts/blog-page.html
@@ -1,5 +1,5 @@
 ---
-layout: doc
+layout: sidebar
 ---
 
 <div id="post-title">
diff --git a/doc-tool/resources/_layouts/doc-page.html b/doc-tool/resources/_layouts/doc-page.html
index 876e90c95..14220aef7 100644
--- a/doc-tool/resources/_layouts/doc-page.html
+++ b/doc-tool/resources/_layouts/doc-page.html
@@ -1,5 +1,5 @@
 ---
-layout: doc
+layout: sidebar
 ---
 
 <h1 id="doc-page-title">{{ page.title }}</h1>
diff --git a/doc-tool/resources/_layouts/doc.html b/doc-tool/resources/_layouts/sidebar.html
index b3947c884..b3947c884 100644
--- a/doc-tool/resources/_layouts/doc.html
+++ b/doc-tool/resources/_layouts/sidebar.html
diff --git a/doc-tool/resources/css/dottydoc.css b/doc-tool/resources/css/dottydoc.css
index aa197de07..54f74b66f 100644
--- a/doc-tool/resources/css/dottydoc.css
+++ b/doc-tool/resources/css/dottydoc.css
@@ -26,6 +26,55 @@ div.index-wrapper {
     overflow-x: hidden;
 }
 
+div#doc-page-container > h1 {
+    border-bottom: 1px solid #eee;
+    padding-bottom: 0.3em;
+}
+
+div#doc-page-container > h1 {
+    margin: 3rem 0 0.5rem 0;
+}
+
+div#doc-page-container > h3 {
+    font-size: 1.5rem;
+}
+
+div#doc-page-container > h4 {
+    font-size: 1.25rem;
+}
+
+div#doc-page-container > h5 {
+    font-size: 1rem;
+}
+
+div#doc-page-container > h1 > a,
+div#doc-page-container > h2 > a,
+div#doc-page-container > h3 > a,
+div#doc-page-container > h4 > a,
+div#doc-page-container > h5 > a,
+div#doc-page-container > h6 > a {
+    text-decoration: none;
+    color: #373a3c;
+}
+
+div#doc-page-container > h1 > a:hover,
+div#doc-page-container > h2 > a:hover,
+div#doc-page-container > h3 > a:hover,
+div#doc-page-container > h4 > a:hover,
+div#doc-page-container > h5 > a:hover,
+div#doc-page-container > h6 > a:hover {
+    text-decoration: underline;
+}
+
+div#doc-page-container > h1 > a:focus,
+div#doc-page-container > h2 > a:focus,
+div#doc-page-container > h3 > a:focus,
+div#doc-page-container > h4 > a:focus,
+div#doc-page-container > h5 > a:focus,
+div#doc-page-container > h6 > a:focus {
+    outline: none;
+}
+
 div#content-body {
     border-left: 1px solid #e0e0e0;
     box-shadow: -3px 0px 5px -2px rgba(0,0,0,0.14);
@@ -232,7 +281,7 @@ div#doc-page-container {
 }
 
 div#doc-page-container > p + h1 {
-    margin-bottom: 40px;
+    margin-bottom: 20px;
 }
 
 div#post-footer > img#author-image {
diff --git a/doc-tool/src/dotty/tools/dottydoc/staticsite/BlogPost.scala b/doc-tool/src/dotty/tools/dottydoc/staticsite/BlogPost.scala
index 4683ed5f9..f68157e40 100644
--- a/doc-tool/src/dotty/tools/dottydoc/staticsite/BlogPost.scala
+++ b/doc-tool/src/dotty/tools/dottydoc/staticsite/BlogPost.scala
@@ -9,17 +9,22 @@ import dotc.config.Printers.dottydoc
 
 import MapOperations._
 
+/**
+ *  A `BlogPost` represents the parsed posts from `./blog/_posts/`
+ *  each post must be named according to the format
+ *  `YYYY-MM-DD-title.{md,html}`
+ */
 class BlogPost(
   val title: String,
   val url: String,
   val date: String,
   val content: String,
   firstParagraph: String,
-  val excerptSep: Option[String],
+  val excerpt_separator: Option[String],
   val categories: JList[String]
 ) {
   import scala.collection.JavaConverters._
-  lazy val excerpt: String = excerptSep match {
+  lazy val excerpt: String = excerpt_separator match {
     case Some(str) => content.split(str).head
     case _ => firstParagraph
   }
@@ -29,7 +34,7 @@ class BlogPost(
     "date" -> date,
     "url" -> url,
     "excerpt" -> excerpt,
-    "excerpt_separator" -> excerptSep.getOrElse(""),
+    "excerpt_separator" -> excerpt_separator.getOrElse(""),
     "content" -> content,
     "categories" -> categories
   ).asJava
diff --git a/doc-tool/src/dotty/tools/dottydoc/staticsite/Site.scala b/doc-tool/src/dotty/tools/dottydoc/staticsite/Site.scala
index ace52725d..895668df2 100644
--- a/doc-tool/src/dotty/tools/dottydoc/staticsite/Site.scala
+++ b/doc-tool/src/dotty/tools/dottydoc/staticsite/Site.scala
@@ -17,6 +17,7 @@ import com.vladsch.flexmark.ext.gfm.strikethrough.StrikethroughExtension
 import com.vladsch.flexmark.ext.gfm.tasklist.TaskListExtension
 import com.vladsch.flexmark.ext.emoji.EmojiExtension
 import com.vladsch.flexmark.ext.autolink.AutolinkExtension
+import com.vladsch.flexmark.ext.anchorlink.AnchorLinkExtension
 import com.vladsch.flexmark.ext.front.matter.YamlFrontMatterExtension
 import com.vladsch.flexmark.util.options.{ DataHolder, MutableDataSet }
 
@@ -292,10 +293,10 @@ case class Site(val root: JFile, val projectTitle: String, val documentation: Ma
 
     val defaultLayouts: Map[String, String] = Map(
       "main" -> "/_layouts/main.html",
-      "doc" -> "/_layouts/doc.html",
+      "sidebar" -> "/_layouts/sidebar.html",
       "doc-page" -> "/_layouts/doc-page.html",
       "api-page" -> "/_layouts/api-page.html",
-      "blog" -> "/_layouts/blog.html",
+      "blog-page" -> "/_layouts/blog-page.html",
       "index" -> "/_layouts/index.html"
     ).mapValues(getResource)
 
@@ -362,6 +363,7 @@ object Site {
         TablesExtension.create(),
         TaskListExtension.create(),
         AutolinkExtension.create(),
+        AnchorLinkExtension.create(),
         EmojiExtension.create(),
         YamlFrontMatterExtension.create(),
         StrikethroughExtension.create()
diff --git a/doc-tool/test/dotty/tools/dottydoc/staticsite/SiteTests.scala b/doc-tool/test/dotty/tools/dottydoc/staticsite/SiteTests.scala
index bb24eb9fb..ba431a5c9 100644
--- a/doc-tool/test/dotty/tools/dottydoc/staticsite/SiteTests.scala
+++ b/doc-tool/test/dotty/tools/dottydoc/staticsite/SiteTests.scala
@@ -19,7 +19,7 @@ class SiteTests extends DottyDocTest {
     assert(site.root.exists && site.root.isDirectory,
            s"'${site.root.getName}' is not a directory")
 
-    val expectedLayouts = Set("main", "index", "blog", "doc", "doc-page", "api-page")
+    val expectedLayouts = Set("main", "index", "sidebar", "blog-page", "doc-page", "api-page")
     assert(site.layouts.keys == expectedLayouts,
            s"Incorrect layouts in: ${site.layouts.keys}, expected: $expectedLayouts")
   }
diff --git a/docs/blog/index.html b/docs/blog/index.html
index b821a25cc..b4725def7 100644
--- a/docs/blog/index.html
+++ b/docs/blog/index.html
@@ -1,5 +1,5 @@
 ---
-layout: blog
+layout: blog-page
 title: "Blog"
 ---
 
diff --git a/docs/docs/usage/dottydoc.md b/docs/docs/usage/dottydoc.md
new file mode 100644
index 000000000..bbfae7081
--- /dev/null
+++ b/docs/docs/usage/dottydoc.md
@@ -0,0 +1,260 @@
+---
+layout: doc-page
+title: Dottydoc
+---
+
+Dottydoc is a tool to generate a combined documentation and API reference for
+your project.
+
+In previous versions of the Scaladoc tool, there is a big divide between what
+is documentation and what is API reference. Dottydoc allows referencing, citing
+and rendering parts of your API in your documentation, thus allowing the two to
+blend naturally.
+
+To do this, Dottydoc is very similar to what [Jekyll](http://jekyllrb.com/)
+provides in form of static site generation. As you probably guessed, this
+whole site was created using Dottydoc.
+
+Creating a site is just as simple as in Jekyll. The site root contains the
+layout of the site and all files placed here will be either considered static,
+or processed for template expansion.
+
+The files that are considered for template expansion must end in `*.{html,md}`
+and will from here on be referred to as "template files" or "templates".
+
+A simple "hello world" site could look something like this:
+
+```
+├── docs
+│   └── getting-started.md
+└── index.html
+```
+
+This will give you a site with the following endpoints:
+
+```
+_site/index.html
+_site/docs/getting-started.html
+```
+
+Just as with Jekyll, the site is rendered in a `_site` directory.
+
+Using existing Templates and Layouts
+====================================
+Dottydoc uses the [Liquid](https://shopify.github.io/liquid/) templating engine
+and provides a number of custom filters and tags specific to Scala
+documentation.
+
+In Dottydoc, all templates can contain YAML front-matter. The front-matter
+is parsed and put into the `page` variable available in templates via Liquid.
+
+To perform template expansion, Dottydoc looks at `layout` in the front-matter.
+Here's a simple example of the templating system in action, `index.html`:
+
+```html
+---
+layout: main
+---
+
+<h1>Hello world!</h1>
+```
+
+With a simple main template like this:
+
+{% raw %}
+```html
+<html>
+    <head>
+        <title>Hello, world!</title>
+    </head>
+    <body>
+        {{ content }}
+    </body>
+</html>
+```
+
+Would result in `{{ content }}` being replaced by `<h1>Hello world!</h1>` from
+the `index.html` file.
+{% endraw %}
+
+Layouts must be placed in a `_layouts` directory in the site root:
+
+```
+├── _layouts
+│   └── main.html
+├── docs
+│   └── getting-started.md
+└── index.html
+```
+
+It is also possible to use one of the [default layouts](#default-layouts) that ship with Dottydoc.
+
+Blog
+====
+Dottydoc also allows for a simple blogging platform in the same vein as Jekyll.
+Blog posts are placed within the `./blog/_posts` directory and have to be on
+the form `year-month-day-title.{md,html}`.
+
+An example of this would be:
+
+```
+├── blog
+│   └── _posts
+│       └── 2016-12-05-implicit-function-types.md
+└── index.html
+```
+
+To be rendered as templates, each blog post should have front-matter and a
+`layout` declaration.
+
+The posts are also available in the variable `site.posts` throughout the site.
+The fields of these objects are the same as in
+[BlogPost](dotty.tools.dottydoc.staticsite.BlogPost).
+
+Includes
+========
+In Liquid, there is a concept of include tags, these are used in templates to
+include other de facto templates:
+
+```html
+<div class="container">
+    {% raw %}{% include "sidebar.html" %}{% endraw %}
+</div>
+```
+
+You can leave out the file extension if your include ends in `.html`.
+
+Includes need to be kept in `_includes` in the site root. Dottydoc provides a
+couple of [default includes](#default-includes), but the user-specified
+includes may override these.
+
+An example structure with an include file "sidebar.html":
+
+```
+├── _includes
+│   └── sidebar.html
+├── blog
+│   ├── _posts
+│   │   └── 2016-12-05-implicit-function-types.md
+│   └── index.md
+└── index.html
+```
+
+Sidebar
+=======
+Dottydoc gives you the ability to create your own custom table of contents,
+this can either be achieved by overriding the `toc.html` include - or by
+providing a `sidebar.yml` file in the site root:
+
+```yaml
+sidebar:
+    - title: Blog
+      url: blog/index.html
+    - title: Docs
+      url: docs/index.html
+    - title: Usage
+      subsection:
+        - title: Dottydoc
+          url: docs/usage/dottydoc.html
+        - title: sbt-projects
+          url: docs/usage/sbt-projects.html
+```
+
+The `sidebar` key is mandatory, as well as `title` for each element. The
+default table of contents allows you to have subsections - albeit the current
+depth limit is 2 - we'd love to see this change, contributions welcome!
+
+The items which have the `subsection` key, may not have a `url` key in the
+current scheme. A site root example with this could be:
+
+```
+├── blog
+│   └── _posts
+│       └── 2016-12-05-implicit-function-types.md
+├── index.html
+└── sidebar.yml
+```
+
+Dottydoc Specific Tags and Behavior
+====================================
+Linking to API
+--------------
+If you for instance, want to link to `scala.collection.immutable.Seq` in a
+markdown file, you can simply use the canonical path in your url:
+
+```markdown
+[Seq](scala.collection.immutable.Seq)
+```
+
+Linking to members is done in the same fashion:
+
+```markdown
+[Seq](scala.collection.immutable.Seq.isEmpty)
+```
+
+Dottydoc denotes objects by ending their names in "$". To select `Object.range`
+you'd therefore write:
+
+```markdown
+[Object.range](scala.collection.immutable.List$.range)
+```
+
+Rendering Docstrings
+--------------------
+Sometimes you end up duplicating the docstring text in your documentation,
+therefore Dottydoc makes it easy to render this inline:
+
+```html
+{% raw %}{% docstring "scala.collection.immutable.Seq" %}{% endraw %}
+```
+
+Other extensions
+----------------
+We would love to have your feedback on what you think would be good in order to
+render the documentation you want! Perhaps you'd like to render method
+definitions or members? Let us know by filing
+[issues](https://github.com/lampepfl/dotty/issues/new)!
+
+Default Layouts
+===============
+main.html
+---------
+A wrapper for all other layouts, includes a default `<head>` with included
+JavaScripts and CSS style-sheets.
+
+### Variables ###
+* `content`: placed in `<body>` tag
+* `extraCSS`: a list of relative paths to extra CSS style-sheets for the site
+* `extraJS`: a list of relative paths to extra JavaScripts for the site
+* `title`: the `<title>` of the page
+
+sidebar.html
+------------
+Sidebar uses `main.html` as its parent layout. It adds a sidebar generated from
+a YAML file (if exists), as well as the index for the project API.
+
+### Variables ###
+* `content`: placed in a `<div>` with class `content-body`
+* `docs`: the API docs generated from supplied source files, this is included by
+  default and does not need to be specified.
+
+doc-page.html
+-------------
+Doc page is used for pages that need a sidebar and provides a small wrapper for
+the included {% raw %}`{{ content}}`{% endraw %}.
+
+api-page.html
+-------------
+The last two layouts are special, in that they are treated specially by
+Dottydoc. The input to the API page is a documented
+[Entity](dotty.tools.dottydoc.model.Entity). As such, this page can be changed
+to alter the way Dottydoc renders API documentation.
+
+blog-page.html
+--------------
+A blog page uses files placed in `./blog/_posts/` as input to render a blog.
+
+Default Includes
+================
+* `scala-logo.svg`: the scala in dotty version as svg
+* `toc.html`: the default table of contents template
diff --git a/docs/sidebar.yml b/docs/sidebar.yml
index 6353b3c90..7ffa1f5b7 100644
--- a/docs/sidebar.yml
+++ b/docs/sidebar.yml
@@ -9,6 +9,8 @@ sidebar:
           url: docs/usage/cbt-projects.html
         - title: sbt-projects
           url: docs/usage/sbt-projects.html
+        - title: Dottydoc
+          url: docs/usage/dottydoc.html
         - title: Migrating
           url: docs/usage/migrating.html
     - title: Contributing
diff --git a/project/Build.scala b/project/Build.scala
index 0abdc99be..d104544c5 100644
--- a/project/Build.scala
+++ b/project/Build.scala
@@ -192,6 +192,7 @@ object DottyBuild extends Build {
                                   "com.vladsch.flexmark" % "flexmark-ext-gfm-tasklist" % "0.11.1",
                                   "com.vladsch.flexmark" % "flexmark-ext-gfm-tables" % "0.11.1",
                                   "com.vladsch.flexmark" % "flexmark-ext-autolink" % "0.11.1",
+                                  "com.vladsch.flexmark" % "flexmark-ext-anchorlink" % "0.11.1",
                                   "com.vladsch.flexmark" % "flexmark-ext-emoji" % "0.11.1",
                                   "com.vladsch.flexmark" % "flexmark-ext-gfm-strikethrough" % "0.11.1",
                                   "com.vladsch.flexmark" % "flexmark-ext-yaml-front-matter" % "0.11.1",