Merge pull request #1071 from chef/im/doc_updates

Updates documentation in chef-workstation
chef · Apr 7, 2020 · ad98a8a · ad98a8a
2 parents 19cfbd2 + 2d28701
commit ad98a8a
Show file tree

Hide file tree

Showing 11 changed files with 40 additions and 44 deletions.
diff --git a/www/Makefile b/www/Makefile
@@ -15,7 +15,7 @@ clean_all:
 	rm -rf results/
 
 serve: assets
-	hugo server --buildDrafts --noHTTPCache --config=config.toml,config_workstation_menu.toml
+	hugo server --buildDrafts --noHTTPCache
 
 lint: assets
 	hugo -D
diff --git a/www/README.md b/www/README.md
@@ -189,16 +189,16 @@ Hugo doesn't handle shortcodes that are indented in a list item properly. It int
 the text of the shortcode as a code block. More complicated shortcodes with
 code blocks, notes, additional list items, or other formatting look pretty
 bad. We've created a simple shortcode for handling shortcodes in lists or definition
-lists called `shortcode_indent`.
+lists called `readFile_shortcode`.
 
 To include a shortcode in a list or definition list, just add its file name
-to the `shortcode` parameter of `shortcode_indent` without the .md suffix.
+to the `file` parameter of `readFile_shortcode`.
 
 For example, if you wanted to add `shortcode_file_name.md` to a list:
 ``` md
-1.  Here is some text introducing the shortcode, but it's not necessary.
+1.  Here is some text introducing the shortcode.
 
-    {{< shortcode_indent shortcode="shortcode_file_name" >}}
+    {{< readFile_shortcode file="shortcode_file_name.md" >}}
 ```
 
 ### Highlighting blocks of text
@@ -265,8 +265,6 @@ users from the deleted page to a new or existing page.
 ├── site
 │   ├── content
 │   │   ├── workstation                 # where to keep markdown file documentation
-│   ├── data
-│   │   ├── chef-workstation            # where to keep structured data files used for data templates
 │   ├── layouts
 |   │   ├── shortcodes
 |   │   │   ├── ws_<shortcode_name>.md  # how to name your workstation-specific shortcodes
@@ -276,6 +274,12 @@ users from the deleted page to a new or existing page.
 |   |   ├── css
 ```
 
+**Data**
+Content in the `data` subdirectory isn't currently included in the Workstation
+documentation on docs.chef.io. If you need to add files to the `data` subdirectory
+that would be included on docs.chef.io, contact the Docs Team and we can include
+that directory.
+
 ### What is happening behind the scenes
 
 The [Chef Documentation](https://docs.chef.io) site uses [Hugo modules](https://gohugo.io/hugo-modules/)

diff --git a/www/content/workstation/_index.md b/www/content/workstation/_index.md
@@ -12,7 +12,7 @@ aliases = ["/about_workstation.html", "/about_chefdk.html", "/chef_dk.html", "/a
     weight = 10
 +++
 
-[\[edit on GitHub\]](https://github.com/chef/chef-workstation/blob/master/www/content/workstation/about_workstation.md)
+[\[edit on GitHub\]](https://github.com/chef/chef-workstation/blob/master/www/content/workstation/_index.md)
 
 {{% ws_chef_workstation %}}
 

diff --git a/www/content/workstation/chef-workstation-app.md b/www/content/workstation/chef-workstation-app.md
@@ -2,8 +2,6 @@
 title = "Chef Workstation App"
 draft = false
 
-aliases = ["/chef_workstation_app.html", "/chef_workstation_app/"]
-
 [menu]
   [menu.workstation]
     title = "Chef Workstation App"
@@ -12,19 +10,8 @@ aliases = ["/chef_workstation_app.html", "/chef_workstation_app/"]
     weight = 61
 +++
 
-+++
-title = "About Berkshelf"
-draft = false
-
-aliases = ["/berkshelf.html", "/berkshelf/"]
+[\[edit on GitHub\]](https://github.com/chef/chef-workstation/blob/master/www/content/workstation/chef-workstation-app.md)
 
-[menu]
-  [menu.workstation]
-    title = "Berkshelf"
-    identifier = "chef_workstation/chef_workstation_tools/berkshelf.md Berkshelf"
-    parent = "chef_workstation/chef_workstation_tools"
-    weight = 10
-+++
 
 # About Chef Workstation App
 

diff --git a/www/content/workstation/config.md b/www/content/workstation/config.md
@@ -2,8 +2,6 @@
 title = "Configure Chef Workstation"
 draft = false
 
-aliases = ["/workstation_config.html", "/workstation_config/"]
-
 [menu]
   [menu.workstation]
     title = "Configure Chef Workstation"
@@ -12,6 +10,9 @@ aliases = ["/workstation_config.html", "/workstation_config/"]
     weight = 50
 +++
 
+[\[edit on GitHub\]](https://github.com/chef/chef-workstation/blob/master/www/content/workstation/config.md)
+
+
 # Configuration
 
 Chef Workstation App and `chef-run` configuration is managed in `config.toml`.

diff --git a/www/content/workstation/ctl_kitchen.md b/www/content/workstation/ctl_kitchen.md
@@ -149,7 +149,7 @@ This subcommand has the following options:
     platforms. Use a Ruby regular expression to glob two or more
     platforms into a single run.
 
-    {{< shortcode_indent shortcode="ws_ctl_kitchen_common_option_platforms" >}}
+    {{< readFile_shortcode file="ws_ctl_kitchen_common_option_platforms.md" >}}
 
 Examples
 --------
@@ -309,7 +309,7 @@ This subcommand has the following options:
     platforms. Use a Ruby regular expression to glob two or more
     platforms into a single run.
 
-    {{< shortcode_indent shortcode="ws_ctl_kitchen_common_option_platforms" >}}
+    {{< readFile_shortcode file="ws_ctl_kitchen_common_option_platforms.md" >}}
 
 Examples
 --------
@@ -445,7 +445,7 @@ This subcommand has the following options:
     platforms. Use a Ruby regular expression to glob two or more
     platforms into a single run.
 
-    {{< shortcode_indent shortcode="ws_ctl_kitchen_common_option_platforms" >}}
+    {{< readFile_shortcode file="ws_ctl_kitchen_common_option_platforms.md" >}}
 
 Examples
 --------
@@ -499,7 +499,7 @@ This subcommand has the following options:
     platforms. Use a Ruby regular expression to glob two or more
     platforms into a single run.
 
-    {{< shortcode_indent shortcode="ws_ctl_kitchen_common_option_platforms" >}}
+    {{< readFile_shortcode file="ws_ctl_kitchen_common_option_platforms.md" >}}
 
 Examples
 --------
@@ -667,7 +667,7 @@ This subcommand has the following options:
     platforms. Use a Ruby regular expression to glob two or more
     platforms into a single run.
 
-    {{< shortcode_indent shortcode="ws_ctl_kitchen_common_option_platforms" >}}
+    {{< readFile_shortcode file="ws_ctl_kitchen_common_option_platforms.md" >}}
 
 Examples
 --------
@@ -725,7 +725,7 @@ This subcommand has the following options:
     platforms. Use a Ruby regular expression to glob two or more
     platforms into a single run.
 
-    {{< shortcode_indent shortcode="ws_ctl_kitchen_common_option_platforms" >}}
+    {{< readFile_shortcode file="ws_ctl_kitchen_common_option_platforms.md" >}}
 
 Examples
 --------
@@ -792,7 +792,7 @@ This subcommand has the following options:
     platforms. Use a Ruby regular expression to glob two or more
     platforms into a single run.
 
-    {{< shortcode_indent shortcode="ws_ctl_kitchen_common_option_platforms" >}}
+    {{< readFile_shortcode file="ws_ctl_kitchen_common_option_platforms.md" >}}
 
 Examples
 --------
@@ -884,7 +884,7 @@ This subcommand has the following options:
     platforms. Use a Ruby regular expression to glob two or more
     platforms into a single run.
 
-    {{< shortcode_indent shortcode="ws_ctl_kitchen_common_option_platforms" >}}
+    {{< readFile_shortcode file="ws_ctl_kitchen_common_option_platforms.md" >}}
 
 Examples
 --------
@@ -942,7 +942,7 @@ This subcommand has the following options:
     platforms. Use a Ruby regular expression to glob two or more
     platforms into a single run.
 
-    {{< shortcode_indent shortcode="ws_ctl_kitchen_common_option_platforms" >}}
+    {{< readFile_shortcode file="ws_ctl_kitchen_common_option_platforms.md" >}}
 
 Examples
 --------
@@ -1009,7 +1009,7 @@ This subcommand has the following options:
     platforms. Use a Ruby regular expression to glob two or more
     platforms into a single run.
 
-    {{< shortcode_indent shortcode="ws_ctl_kitchen_common_option_platforms" >}}
+    {{< readFile_shortcode file="ws_ctl_kitchen_common_option_platforms.md" >}}
 
 Examples
 --------
@@ -1144,7 +1144,7 @@ This subcommand has the following options:
     platforms. Use a Ruby regular expression to glob two or more
     platforms into a single run.
 
-    {{< shortcode_indent shortcode="ws_ctl_kitchen_common_option_platforms" >}}
+    {{< readFile_shortcode file="ws_ctl_kitchen_common_option_platforms.md" >}}
 
 Examples
 --------

diff --git a/www/content/workstation/privacy.md b/www/content/workstation/privacy.md
@@ -2,8 +2,6 @@
 title = "Privacy and Telemetry"
 draft = false
 
-aliases = ["/privacy.html", "/privacy/"]
-
 [menu]
   [menu.workstation]
     title = "Privacy and Telemetry"
@@ -12,6 +10,8 @@ aliases = ["/privacy.html", "/privacy/"]
     weight = 20
 +++
 
+[\[edit on GitHub\]](https://github.com/chef/chef-workstation/blob/master/www/content/workstation/privacy.md)
+
 In order to continually improve Chef Workstation, we collect information to help us identify bugs and understand how people interact with Chef Workstation.
 
 What We Collect

diff --git a/www/content/workstation/troubleshooting.md b/www/content/workstation/troubleshooting.md
@@ -2,8 +2,6 @@
 title = "Troubleshooting"
 draft = false
 
-aliases = ["troubleshooting.html", "/troubleshooting/"]
-
 [menu]
   [menu.workstation]
     title = "Troubleshooting"
@@ -12,6 +10,9 @@ aliases = ["troubleshooting.html", "/troubleshooting/"]
     weight = 60
 +++
 
+[\[edit on GitHub\]](https://github.com/chef/chef-workstation/blob/master/www/content/workstation/troubleshooting.md)
+
+
 Chef Workstation Logs
 =====================
 

diff --git a/www/layouts/shortcodes/ws_knife_ssl_check_bad_ssl_certificate.md b/www/layouts/shortcodes/ws_knife_ssl_check_bad_ssl_certificate.md
@@ -29,7 +29,7 @@ If the server you are connecting to uses a self-signed certificate,
 you must configure chef to trust that certificate.
 
 By default, the certificate is stored in the following location on the
-host where your chef-server runs:
+host where your Chef Infra Server runs:
 
   /var/opt/opscode/nginx/ca/SERVER_HOSTNAME.crt
 

diff --git a/www/themes/docs-new/layouts/shortcodes/readFile_shortcode.html b/www/themes/docs-new/layouts/shortcodes/readFile_shortcode.html
@@ -1,6 +1,10 @@
 
 {{ readFile (delimit (slice "layouts/shortcodes/" (.Get "file")) "") | markdownify }}
 
-{{/* This shortcode is used only for processing other shortcodes that have a code block
-  that contains the less than character "<". For some reason Hugo converts that
-  to its html equivalent &lt; in the html output.*/}}
+{{/* This shortcode is used for two purposes.
+  1. Some shortcodes contain a code block with less than character "<". For some
+  reason Hugo converts that to its html equivalent &lt; in the html output.
+
+  2. Shortcodes that are indented because they're in a list don't display properly
+  in the normal method that we use to add shortcodes, {{% shortcode_name %}}. Use
+  this readFile shortcode to include those shortcodes instead.*/}}
diff --git a/www/themes/docs-new/layouts/shortcodes/shortcode_indent.html b/www/themes/docs-new/layouts/shortcodes/shortcode_indent.html