web-api readme, and documentation homepage.

improve styles on documentation site to fix the header, tweak the in-page styles, build an in-document focussed navigation.
slackapi · Mar 22, 2019 · 0be167b · 0be167b
1 parent 4566337
commit 0be167b
Show file tree

Hide file tree

Showing 19 changed files with 824 additions and 494 deletions.
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -57,6 +57,8 @@ google_tag_manager: GTM-KFZ5MK7
 
 # Plugin settings
 markdown: kramdown
+kramdown:
+  parse_block_html: true
 plugins:
   - jemoji
   - jekyll-redirect-from

diff --git a/docs/_includes/focussed_nav.html b/docs/_includes/focussed_nav.html
@@ -5,7 +5,9 @@
 </div>
 
 <div class="sidebar_menu invisible_until_anchor">
-    <h4 class="sidebar_menu_header">Recipes</h4>
+    {% if page.anchor_links_header %}
+    <h4 class="sidebar_menu_header">{{ page.anchor_links_header }}</h4>
+    {% endif %}
     <ul class="sidebar_menu_list">
         <li class="anchor_template"><a href="#" class="sidebar_menu_list_item"></a></li>
     </ul>

diff --git a/docs/_packages/web_api.md b/docs/_packages/web_api.md
diff --git a/docs/_tutorials/migrating_to_v5.md b/docs/_tutorials/migrating_to_v5.md
@@ -0,0 +1,5 @@
+---
+title: Migrating to v5.x
+order: 1
+slug: migrating_to_v5
+---
diff --git a/docs/styles/docs.css b/docs/styles/docs.css
@@ -3,11 +3,24 @@ body {
   font-family: Slack-Lato,appleLogo,sans-serif;
 }
 
-/* Replaces old sidebar styled links */
-.sidebar_menu h5 {
-  font-size: 0.8rem;
-  font-weight: 800;
-  margin-bottom: 3px;
+/*
+ * Unfix the header position. Otherwise, anchor links take you to a spot on the page that's covered.
+ * The API site fixes this by offsetting anchor tags from the headers in a weird and also error-prone way.
+ * It's a better tradeoff to unfix the header, and the side benefit is we get some screen space back.
+ */
+body > header {
+  position: initial;
+}
+@media only screen and (min-width: 641px) {
+  .api #page_contents {
+    padding-top: 2rem;
+    padding-bottom: 2rem;
+  }
+}
+@media only screen and (max-width: 640px) {
+  #page_contents {
+    margin-top: 0;
+  }
 }
 
 /* Aligns footer navigation to the left of the sidebar */
@@ -47,7 +60,6 @@ footer {
   font-weight: 600;
   font-size: 1.1rem;
 }
-
 .nav_home_icon {
   vertical-align: middle;
 }
@@ -57,6 +69,18 @@ footer {
   visibility: hidden;
 }
 
+/* Details tags aren't styled in the rollup, but need the same margin bottom as paragraphs */
+details {
+  margin-bottom: 1rem;
+}
+summary > strong > i {
+  font-style: normal;
+}
+
+/*
+ * ☁️ Maybe one day, #page_contents will be able to go beyond a fixed width...
+ */
+
 /*
  * Github theme stylesheet from: http://jwarby.github.io/jekyll-pygments-themes/languages/javascript.html
  */

diff --git a/node-slack-sdk.code-workspace b/node-slack-sdk.code-workspace
@@ -9,16 +9,16 @@
 			"path": "packages/web-api"
 		},
 		{
-			"name": "RTM API",
-			"path": "packages/rtm-api"
+			"name": "Events API",
+			"path": "packages/events-api"
 		},
 		{
 			"name": "Interactive Messages",
 			"path": "packages/interactive-messages"
 		},
 		{
-			"name": "Events API",
-			"path": "packages/events-api"
+			"name": "RTM API",
+			"path": "packages/rtm-api"
 		},
 		{
 			"name": "Incoming Webhook",

diff --git a/packages/client/README.md b/packages/client/README.md
@@ -1,11 +0,0 @@
-# `client`
-
-> TODO: description
-
-## Usage
-
-```
-const client = require('client');
-
-// TODO: DEMONSTRATE API
-```

diff --git a/packages/client/package.json b/packages/client/package.json
@@ -30,7 +30,7 @@
     "npm": ">= 5.5.1"
   },
   "repository": "slackapi/node-slack-sdk",
-  "homepage": "https://slack.dev/node-slack-sdk",
+  "homepage": "https://slack.dev/node-slack-sdk/tutorials/migrating_to_v5/",
   "publishConfig": {
     "access": "public"
   },

diff --git a/packages/events-api/package.json b/packages/events-api/package.json
@@ -27,7 +27,7 @@
     "node": ">=4.2.0"
   },
   "repository": "slackapi/node-slack-sdk",
-  "homepage": "https://slack.dev/node-slack-sdk",
+  "homepage": "https://slack.dev/node-slack-sdk/events-api",
   "publishConfig": {
     "access": "public"
   },

diff --git a/packages/interactive-messages/package.json b/packages/interactive-messages/package.json
@@ -31,7 +31,7 @@
     "node": ">=4.2.0"
   },
   "repository": "slackapi/node-slack-sdk",
-  "homepage": "https://slack.dev/node-slack-sdk",
+  "homepage": "https://slack.dev/node-slack-sdk/interactive-messages",
   "publishConfig": {
     "access": "public"
   },

diff --git a/packages/logger/README.md b/packages/logger/README.md
@@ -1,11 +0,0 @@
-# `logger`
-
-> TODO: description
-
-## Usage
-
-```
-const logger = require('logger');
-
-// TODO: DEMONSTRATE API
-```

diff --git a/packages/rtm-api/README.md b/packages/rtm-api/README.md
diff --git a/packages/rtm-api/package.json b/packages/rtm-api/package.json
@@ -26,7 +26,7 @@
     "npm": ">= 5.5.1"
   },
   "repository": "slackapi/node-slack-sdk",
-  "homepage": "https://slack.dev/node-slack-sdk",
+  "homepage": "https://slack.dev/node-slack-sdk/rtm-api",
   "publishConfig": {
     "access": "public"
   },

diff --git a/packages/types/README.md b/packages/types/README.md
@@ -1,11 +0,0 @@
-# `types`
-
-> TODO: description
-
-## Usage
-
-```
-const types = require('types');
-
-// TODO: DEMONSTRATE API
-```