Merge branch 'main' into bolt-tslint-to-eslint

.github/maintainers_guide.md

@@ -28,6 +28,18 @@ All documentation contains [front matter](https://jekyllrb.com/docs/front-matter
 
 To build the docs locally, you can run `bundle exec jekyll serve`.
 
+#### Adding beta documentation
+When documentation is in a beta state, it requires a new, distinct collection of docs. The process is a little nuanced, so make sure to build the documentation locally to make sure it appears how you expect. To create a new collection:
+1. Add content
+* Add a new folder to docs with an underscore (ex: `_steps`).
+* Add documentation sections to that folder, with similar front matter to the `_advanced` and `_basic` sections.
+* Add an overview section that explains the beta state of the category. This should always be `order: 1` in the front matter.
+
+2. Configure layout
+* Update `docs`>`_config.yml` with the new collection you created under `collections` (the same as the folder name - ex: `steps`). While you're there, add the sidebar title under `t`.
+* In `docs`>`_layouts`>`default.html` make a copy of the `basic` or `advanced` section, and modify the div ID and content to correspond to your beta collection. This step requires you to use variables from `_config.yml`.
+* Now in `docs`>`_includes`>`sidebar.html`, create a new section after the basic and advanced sections. Again, copy the `basic` or `advanced` section to use as a template. Be careful with the variable naming—it's a little more complex than in `default.html`, and requires you to use variables from `_config.yml`.
+
 ### Releasing
 
 1.  Create the commit for the release:

docs/_config.yml

@@ -13,6 +13,8 @@ collections:
     output: false
   advanced:
     output: false
+  steps:
+    output: false
   tutorials:
     output: true
     permalink: /tutorials/:slug
@@ -31,11 +33,14 @@ t:
     basic: Basic concepts
     advanced: Advanced concepts
     start: Getting started
+    steps: Workflow steps
     contribute: Contributing
   ja-jp:
     basic: 基本的な概念
     advanced: 応用コンセプト
     start: Bolt 入門ガイド
+    # TODO: translate this title
+    steps: Workflow steps
     contribute: 貢献
 
 # Metadata

docs/_includes/sidebar.html

@@ -35,22 +35,33 @@
   </ul>
 
   <ul class="sidebar-section">
-
     <a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/concepts#advanced">
       <li class="title">{{ site.t[page.lang].advanced }}</li>
     </a>
     {% assign advanced_sections = site.advanced | sort: "order" | where: "lang", page.lang %}
     {% for section in advanced_sections %}
       <a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/concepts#{{ section.slug }}">
-        <li>
-          {% if section.beta == true %}
-            <span class="beta">Beta</span>
-          {% endif %}
-         {{section.title}}
-        </li>
+        <li>{{section.title}}</li>
+      </a>
+    {% endfor %}
+  </ul>
+
+
+
+  <!--Start (temporary) beta sections. At the moment, there's no ja-jp documentation for this feature-->
+
+  <ul class="sidebar-section">
+    <a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/concepts#steps">
+      <li class="title"><span class="beta">Beta</span> {{ site.t[page.lang].steps }}</li>
+    </a>
+    {% assign workflow_steps = site.steps | sort: "order" | where: "lang", page.lang %}
+    {% for step in workflow_steps %}
+      <a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/concepts#{{ step.slug }}">
+        <li>{{step.title}}</li>
       </a>
     {% endfor %}
   </ul>
+  <!--End (temporary) beta sections-->
 
   <ul class="sidebar-section">
     {% assign tutorials = site.tutorials | where: "lang", page.lang | where_exp: "tutorial", "tutorial.order > 0" %}

docs/_layouts/default.html

@@ -44,6 +44,21 @@ <h3 id="{{section.slug}}">{{ section.title }}</h3>
           </div>
         {% endfor %}
         </div>
+
+        <!--Start (temporary) beta sections-->
+        <div id="steps">
+          {% assign workflow_steps = site.steps | sort: "order" | where: "lang", page.lang %}
+          {% for section in workflow_steps %}
+          <div class="section-wrapper">
+            <h3 id="{{section.slug}}"><span class="beta">Beta</span> {{ section.title }}</h3>
+
+            {{ section.content | markdownify }}
+
+            <hr>
+          </div>
+        {% endfor %}
+        </div>
+        <!--End (temporary) beta sections-->
     </div>
 
   </div>

docs/_advanced/configuring_workflow_steps.md → docs/_steps/configuring_workflow_steps.md

@@ -2,13 +2,11 @@
 title: Configuring and updating workflow steps
 lang: en
 slug: configuring-steps
-order: 10
+order: 2
 beta: true
 ---
 {% raw %} 
 <div class='section-content'>
-⚠️ Workflow [steps from apps](https://api.slack.com/workflows/steps) is a beta feature. As the feature is developed, **Bolt for JavaScript's API will change to add better native support.** To develop with workflow steps in Bolt, use the `@slack/bolt@feat-workflow-steps` version of the package rather than the standard `@slack/bolt`.
-
 When a builder is adding your step to a new or existing workflow, your app will need to configure and update that step:
 
 **1. Listening for `workflow_step_edit` action**

docs/_advanced/executing_workflow_steps.md → docs/_steps/executing_workflow_steps.md

@@ -2,12 +2,11 @@
 title: Executing workflow steps
 lang: en
 slug: executing-steps
-order: 11
+order: 3
 beta: true
 ---
 
 <div class="section-content">
-⚠️ Workflow [steps from apps](https://api.slack.com/workflows/steps) is a beta feature. As the feature is developed, **Bolt for JavaScript's API will change to add better native support.** To develop with workflow steps in Bolt, use the `@slack/bolt@feat-workflow-steps` version of the package rather than the standard `@slack/bolt`.
 
 When your workflow is executed by an end user, your app will receive a `workflow_step_execute` event. This event includes the user's `inputs` and a unique workflow execution ID. Your app must either call [`workflows.stepCompleted`](https://api.slack.com/methods/workflows.stepCompleted) with the `outputs` you specified in `workflows.updateStep`, or [`workflows.stepFailed`](https://api.slack.com/methods/workflows.stepFailed) to indicate the step failed.
 </div>

docs/_steps/workflow_steps_beta.md

@@ -0,0 +1,13 @@
+---
+title: Overview of Workflow Steps for apps
+lang: en
+slug: steps-beta
+order: 1
+beta: true
+---
+
+<div class="section-content">
+⚠️ Workflow [steps from apps](https://api.slack.com/workflows/steps) is a beta feature. As the feature is developed, **Bolt for JavaScript's API will change to add better native support.** To develop with workflow steps in Bolt, use the `@slack/bolt@feat-workflow-steps` version of the package rather than the standard `@slack/bolt`.
+
+The [API documentation](https://api.slack.com/workflows/steps) includes more information on setting up a beta app.
+</div>

docs/assets/style.css

@@ -20,6 +20,18 @@ body {
   grid-area: content;
 }
 
+span.beta {
+  background-color: #E8F5FA;
+  color: #1264A3;
+  padding: 4px 9px;
+  margin-right: 2px;
+  border-radius: 16px;
+  border: 1px solid #D4ECF6;
+  text-transform: uppercase;
+  font-weight: 600;
+  font-size: 0.7em;
+}
+
 /* Sidebar */
 .panel {
   position: fixed;
@@ -83,18 +95,6 @@ body {
   color: var(--black);
 }
 
-.panel .sidebar-content ul.sidebar-section li span.beta {
-  background-color: #E8F5FA;
-  color: #1264A3;
-  padding: 2px 6px;
-  margin-right: 2px;
-  border-radius: 6px;
-  border: 1px solid #D4ECF6;
-  text-transform: uppercase;
-  font-weight: 600;
-  font-size: 0.8em;
-}
-
 .panel .sidebar-content ul.sidebar-section li:hover {
   background-color: #D7D7D7;
 }