Writing an Update or Case Study

Updates and Case Studies use the same styles and markdown as articles, but have a few extra attributes that you can use to change how they're shown in different places across the site. You'll also need to build the related files, like the listing page, feeds, book.yaml and the tags pages using gulp.

Quick Start

To get started quickly, copy the template and start there.

  1. Make a copy of the template (showcase or update), and place it in the appropriate directory.
  2. Update the key fields:
    • book_path
    • description
    • wf_updated_on & wf_published_on use the format YYYY-MM-DD (2016-12-31)
    • wf_featured_image & wf_featured_snippet
    • Update the contributor include
  3. Run gulp build to get it listed in the listing pages and table of contents
  4. Write/iterate on the update or showcase
  5. Before submitting the pull request, run gulp test to verify everything is happy
  6. Submit your PR with the appropriate changes.

YAML Front Matter & Special Attributes

Refer to the YAML Front Matter section for full details on the required YAML front matter.

Tags

To make it easier to find or group posts, /web/updates/ supports tagging posts. Simply add a wf_tags block with a comma separated list of tags.

{# wf_tags: devtools,geolocation,gulp,getusermedia #}

To specify a featured image used on listing pages and within the feeds, add a wf_featured_image tag. To ensure this works in feeds, the URL provided should be an absolute page on DevSite.

{# wf_featured_image: /web/updates/images/weird.jpg #}

Images should be 16x9, ideally 800px by 450px.

Looking for a generic image? Check out the generic images folder.

The featured snippet is used as the snippet for listing pages. If it is not provided, we'll try to use the description. The snippet is not limited by length, and can include HTML.

{# wf_featured_snippet: Use <kbd class='kbd'>Cmd + ]</kbd>... #}

Comment Blocks

Comment blocks are not automatically added to update pages. To allow users to comment on your documentation, you must the comment widget to the bottom of the page. For example:

{% include "comment-widget.html" %}

Once you've created your update, you'll need to generate the related files, like the listing page, update the _book.yaml, etc. To do that, run:

gulp build