Merge pull request #184 from justwriteclick/build

Updates links

Author: annegentle

_learn/07-evaluating-ssg-themes.md

@@ -15,7 +15,7 @@ Here's a short list of questions you may want to ask about the theme you use for
 ## Admonitions or notes
 Are there designs for output of levels of admonition, such as warning, information, and note?
 
-Advanced admonitions can enable substituting custom text instead of "Note" or "Warning," or custom icons. You can also configure the admonitions in some themes to expand or contract in-page. For example, look at the variations for Markdown source with the [Mkdocs Material theme when using the admonition extension](https://squidfunk.github.io/mkdocs-material/extensions/admonition/). Or, when using [RST with the Read the Docs theme, you have lots of directives](https://sphinx-rtd-theme.readthedocs.io/en/latest/demo/demo.html#admonitions) to choose from, including Attention, Hint, Important, Note, Tip, Error, or Danger, or write your own. You should also test if code blocks work within an admonition if that is important in your documentation.
+Advanced admonitions can enable substituting custom text instead of "Note" or "Warning," or custom icons. You can also configure the admonitions in some themes to expand or contract in-page. For example, look at the variations for Markdown source with the [Mkdocs Material theme when using the admonition extension](https://squidfunk.github.io/mkdocs-material/reference/admonitions/). Or, when using [RST with the Read the Docs theme, you have lots of directives](https://sphinx-rtd-theme.readthedocs.io/en/latest/demo/demo.html#admonitions) to choose from, including Attention, Hint, Important, Note, Tip, Error, or Danger, or write your own. You should also test if code blocks work within an admonition if that is important in your documentation.
 
 ![Note, Tip, Error, oh my](/images/learn/rtd-admonitions.png)
 

_posts/articles/2016-09-23-doc-issues-tracking.md

@@ -24,7 +24,7 @@ It's a pretty simple request:
 
 You can then pre-fill with additional information to help you or other collaborators fix the bug, such as the source file and when it was merged into the repository.
 
-All these concerns can be addressed with a great [Issues template](https://github.com/blog/2111-issue-and-pull-request-templates). To make an Issue template for a GitHub docs repository, save a file named ISSUE_TEMPLATE in the root directory that contains the information you need in Markdown format. Add headings, links, @-mentions, and task lists to your Issue template.
+All these concerns can be addressed with a great [Issues template](https://github.blog/2016-02-17-issue-and-pull-request-templates/). To make an Issue template for a GitHub docs repository, save a file named ISSUE_TEMPLATE in the root directory that contains the information you need in Markdown format. Add headings, links, @-mentions, and task lists to your Issue template.
 
 In OpenStack, we use [JavaScript](https://github.com/openstack/openstackdocstheme/blob/master/openstackdocstheme/theme/openstackdocs/static/js/docs.js#L119) to pre-fill the bug form with the page title, URL, a link to the source file itself, and any tags to add to the logged doc bug. I'm sure you could adopt something similar in your static site generator as well.
 

_posts/articles/2017-06-05-free-open-source-api-doc-tools.md

@@ -40,7 +40,7 @@ Example of an API documentation displayed with the Swagger UI
 
 Swagger is free to use, licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0). You can find all Swagger-related public tools under the [swagger-api GitHub account](https://github.com/swagger-api).
 
-Many [open source projects](https://swagger.io/open-source-integrations/) and [commercial vendors](https://swagger.io/commercial-tools/) provide Swagger integrations, so make sure to check out the list of available solutions before building new tooling - there is a big chance you will find an existing solution that fits the needs of your project.
+Many [open source projects](https://swagger.io/open-source-integrations/) and [tools vendors](https://swagger.io/tools/) provide Swagger integrations, so make sure to check out the list of available solutions before building new tooling - there is a big chance you will find an existing solution that fits the needs of your project.
 
 As today’s leading API ecosystem, it’s also the best documented and supported. Should you decide to document your APIs with Swagger, you can find plenty of resources, tutorials, examples and help online.
 
@@ -54,7 +54,7 @@ To create your API documentation with DapperDox, point DapperDox at your **OpenA
 
 ### ReDoc
 
-[ReDoc](https://github.com/Rebilly/ReDoc) uses the OpenAPI specification and generates a responsive site with a three-panel design. It pulls markdown headings from the OpenAPI description field into the side menu, and supports deep linking.
+[ReDoc](https://github.com/Redocly/redoc) uses the OpenAPI specification and generates a responsive site with a three-panel design. It pulls markdown headings from the OpenAPI description field into the side menu, and supports deep linking.
 
 ReDoc aims to make deployment extremely easy, provides a wide support for OpenAPI objects, and offers interactive documentation for nested objects. You can include code samples via a third-party extension.
 
@@ -98,7 +98,7 @@ Thanks to its broad adoption there is a wide range of tools built for API Bluepr
 
 ### Snowboard
 
-[Snowboard](https://github.com/subosito/snowboard) is an API Blueprint parser and renderer. It offers a colourful default theme illustrating API request types and responses, and can also be used with custom templates.
+[Snowboard](https://github.com/bukalapak/snowboard) is an API Blueprint parser and renderer. It offers a colourful default theme illustrating API request types and responses, and can also be used with custom templates.
 
 <img src="../../images/pronovix/snowboard_example.png" alt="Snowboard example" width="800" />
 
@@ -118,7 +118,7 @@ Other free and open source API documentation generators
 Besides the ones detailed above, there are plenty of different open source API documentation generators for different languages and API specifications. Here’s a brief summary of the ones we’ve explored:
 
 -   [I/O Docs](https://github.com/mashery/iodocs): I/O docs is an API definition format for the TIBCO Mashery network that comes with a live interactive documentation system for RESTful web APIs. By defining APIs at the resource, method and parameter levels in a JSON schema, I/O Docs will generate a JavaScript client interface.
--   [Slate](https://github.com/lord/slate): Slate helps you create responsive API documentation with a clean, intuitive design. Although it’s built in Ruby, when you write docs with Slate, you're just writing Markdown, which makes it simple to edit and understand. By default, your Slate-generated documentation is hosted in a public Github repository, which makes it simple for other developers to make pull requests to your docs if they find typos or other problems. Of course, if you don't want to use GitHub, you can also host your docs elsewhere.
+-   [Slate](https://github.com/slatedocs/slate): Slate helps you create responsive API documentation with a clean, intuitive design. Although it’s built in Ruby, when you write docs with Slate, you're just writing Markdown, which makes it simple to edit and understand. By default, your Slate-generated documentation is hosted in a public Github repository, which makes it simple for other developers to make pull requests to your docs if they find typos or other problems. Of course, if you don't want to use GitHub, you can also host your docs elsewhere.
 -   [Whiteboard](https://github.com/mpociot/whiteboard): A NodeJS based project started from Slate.
 -   [apiDoc](https://apidocjs.com/): Inline documentation for RESTful web APIs, that creates a documentation from API annotations in your source code.
 -   [CUUBEZ API Visualizer](https://github.com/cuubez/api-visualizer): Java based API solution to visualize the documentation of RESTful web APIs. This API visualizing framework supports all JAXRS based java REST frameworks and non-JAXRS java based REST frameworks that are currently available in the industry.
@@ -141,7 +141,7 @@ A couple of documentation tools you can check out:
 -   [Dexy](https://www.dexy.it/): Dexy is a multi-purpose project automation tool with lots of features designed to work with documents. It does the repetitive parts for you, and thus makes it easier to create technical documents. Many developers use it to document APIs, because combined with other open source tools, Dexy is able to run your example code, save the results, fetch data from an API, and post your docs to a blog or a wiki.
 -->
 -   [Docco](https://jashkenas.github.io/docco/): Docco is a quick-and-dirty documentation generator. It produces an HTML document that displays your comments intermingled with your code.
--   [Doxygen](https://doxygen.nl/): Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C\#, PHP, Java, Python, IDL, Fortran, VHDL, Tcl, and to some extent D. To document your API, generate an online HTML documentation browser or an offline reference manual, and configure Doxygen to extract the code structure from your source files.
+-   [Doxygen](https://doxygen.nl/index.html): Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C\#, PHP, Java, Python, IDL, Fortran, VHDL, Tcl, and to some extent D. To document your API, generate an online HTML documentation browser or an offline reference manual, and configure Doxygen to extract the code structure from your source files.
 
 We mentioned these tools to give you an idea of how you can use general documentation tools for API documentation, but there are many more to choose from, if you’d like to follow this approach.
 
@@ -214,7 +214,7 @@ Interactive, responsive documentation</td>
 <td>Snowboard</td>
 <td>API Blueprint renderer</td>
 <td>API Blueprint</td>
-<td><a href="https://htmlpreview.github.io/?https://github.com/subosito/snowboard/blob/master/examples/alpha/Real%20World%20API.html">Snowboard demo</a></td>
+<td><a href="https://htmlpreview.github.io/?https://github.com/bukalapak/snowboard/blob/v3/examples/winter/Real%20World%20API.html">Snowboard demo</a></td>
 </tr>
 <tr class="odd">
 <td>Aglio</td>
@@ -237,7 +237,7 @@ Collaboration through GitHub</td>
 <td><br />
 Markdown (Ruby)</td>
 <td><br />
-<a href="https://lord.github.io/slate/">Slate demo</a></td>
+<a href="https://slatedocs.github.io/slate">Slate demo</a></td>
 </tr>
 <tr class="even">
 <td>Whiteboard</td>

_posts/articles/2018-02-12-change-case-study.md

@@ -235,7 +235,7 @@ Almost everyone on the team was happy about the way our doc solution turned out.
 
 I outlined the challenges here to reinforce the fact that implementing docs-as-code is no small undertaking. It doesn't have to be an endeavor that takes months, but at a large company, if you're integrating with engineering infrastructure and building out a process that will scale and grow, it can require a decent amount of engineering expertise and effort.
 
-If you're implementing docs-as-code at a small company, you can simplify processes and use a system that meets your needs. For example, you could simply use [GitHub Pages](https://pages.github.com/), or use the [S3_website plugin](https://github.com/laurilehmijoki/s3_website) to publish on AWS S3, or better yet, use a continuous deployment platform like [CloudCannon](https://cloudcannon.com/) or [Netlify](https://www.netlify.com/). (I explore these tools in more depth here: [Publishing tool options for developer docs](https://idratherbewriting.com/learnapidoc/pubapis_docs_as_code_tool_options.html).) I might have opted for either of these approaches if allowed and if we didn't have an engineering support team to implement the workflow I described.
+If you're implementing docs-as-code at a small company, you can simplify processes and use a system that meets your needs. For example, you could simply use [GitHub Pages](https://pages.github.com/), or use the [S3_website plugin](https://github.com/laurilehmijoki/s3_website) to publish on AWS S3, or better yet, use a continuous deployment platform like [CloudCannon](https://cloudcannon.com/) or [Netlify](https://www.netlify.com/). (I explore these tools in more depth here: [Publishing tool options for developer docs](https://idratherbewriting.com/learnapidoc/pubapis_docs_as_code.html).) I might have opted for either of these approaches if allowed and if we didn't have an engineering support team to implement the workflow I described.
 
 ## Blog posts about docs-as-code tools
 

_posts/articles/2018-10-12-platformos-1of4.md

@@ -8,12 +8,12 @@ author: diana_lakatos
 tags: [developer documentation, Design Thinking, Information Architecture, docs, documentation, UX]
 image:
   path: /images/platformos/platformos_part1/part1_cover.jpg
-  caption: "[Courtesy platformOS blog](https://www.platform-os.com/blog/post/building-our-documentation-site-on-platform-os-part-1-information-architecture)"
+  caption: "[Courtesy platformOS blog](https://www.platformos.com/blog/post/building-our-documentation-site-on-platform-os-part-1-information-architecture)"
 comments: false
 share: true
 ---
 
-This article series describes our process of building our [documentation site](https://documentation.platform-os.com/) for [platformOS](https://www.platform-os.com/), with in-depth insights into our approach, decisions, and plans. We have planned four parts for this series, each describing a unique aspect of our journey:  
+This article series describes our process of building our [documentation site](https://documentation.platformos.com/) for [platformOS](https://www.platformos.com/), with in-depth insights into our approach, decisions, and plans. We have planned four parts for this series, each describing a unique aspect of our journey:  
 
 * Part 1: **Information Architecture**  
   In this part, we share how we started, how we got to know our audience, how we figured out what content we need, and how we outlined a sitemap for our documentation site.
@@ -89,7 +89,7 @@ Based on the Content Inventory and the results of the Card Sorting sessions, we
 
 _Sample page from our sitemap_  
 
-We have already changed some parts of our sitemap based on new information we gathered and business decisions we made. For example, we are now planning to build a separate community site, instead of having a community section on our documentation site. We decided to link to content on [platform-os.com](https://www.platform-os.com/blog/post/platform-os-blog-module) (like the blog, terms & conditions, etc.) in the beginning to focus on other parts of the site, and reevaluate these sections later. We believe that both product and content development can benefit from a process that allows for such flexibility.  
+We have already changed some parts of our sitemap based on new information we gathered and business decisions we made. For example, we are now planning to build a separate community site, instead of having a community section on our documentation site. We decided to link to content on [platformos.com](https://www.platformos.com/blog/post/platform-os-blog-module) (like the blog, terms & conditions, etc.) in the beginning to focus on other parts of the site, and reevaluate these sections later. We believe that both product and content development can benefit from a process that allows for such flexibility.  
 
 ### Persona-based content prioritization
 
@@ -109,6 +109,6 @@ This concluded our Information Architecture phase. We have discovered and organi
 
 _We involved [UX Strategist Katalin Nagygyörgy](https://www.linkedin.com/in/nagygyorgykatalin/) in our process from the start. Through our collaboration, we could extract and collect all the necessary information using tried and true research methodologies and UX best practices._
 
-_This article was originally written for the [platformOS Blog](https://www.platform-os.com/blog/post/building-our-documentation-site-on-platformos-part-1-information-architecture)._
+_This article was originally written for the [platformOS Blog](https://www.platformos.com/blog/post/building-our-documentation-site-on-platformos-part-1-information-architecture)._
 
 {% include sign-up.html %}

_posts/articles/2018-11-01-platformos-2of4.md

@@ -8,12 +8,12 @@ author: diana_lakatos
 tags: [developer documentation, Content-First Design, community, style guide, templates, editorial workflow, wireframes, docs, documentation, UX]
 image:
   path: /images/platformos/platformos_part2/part2_cover.jpg
-  caption: "[Courtesy platformOS Blog](https://www.platform-os.com/blog/post/building-our-documentation-site-on-platform-os-part-2-content-production-and-layouts)"
+  caption: "[Courtesy platformOS Blog](https://www.platformos.com/blog/post/building-our-documentation-site-on-platform-os-part-2-content-production-and-layouts)"
 comments: false
 share: true
 ---
 
-Welcome to part 2 of our article series where we describe the process of building the [platformOS documentation site](https://documentation.platform-os.com/) from discovery to development, with in-depth insights into our approach, decisions, plans, and technical implementation.
+Welcome to part 2 of our article series where we describe the process of building the [platformOS documentation site](https://documentation.platformos.com/) from discovery to development, with in-depth insights into our approach, decisions, plans, and technical implementation.
 
 Now that you’ve seen how we explored the needs of our audience, outlined the types of content we’d work on, and created a sitemap in part 1, let’s move on to discuss how content production started, and how we created the layouts and navigation for the site.  
 
@@ -37,7 +37,7 @@ We also wanted to provide tools to make it easy for our users to contribute docu
 
 # Style Guide
 
-To ensure a consistent communication style throughout our documentation, we started with defining our standards for grammar, syntax, and the different types of technical content we have, in our [style guide](https://documentation.platform-os.com/style-guide/documentation-style-guide).  
+To ensure a consistent communication style throughout our documentation, we started with defining our standards for grammar, syntax, and the different types of technical content we have, in our [style guide](https://documentation.platformos.com/style-guide/documentation-style-guide).  
 
 Our style guide is just as much a work in progress as our documentation, but we’ve defined the basics that internal or external contributors need:  
 
@@ -142,6 +142,6 @@ We hope you enjoyed learning about how we started content production, how we bui
 
 _We involved [UX Strategist Katalin Nagygyörgy](https://www.linkedin.com/in/nagygyorgykatalin/) in our process from the start. Through our collaboration, we could extract and collect all the necessary information using tried and true research methodologies and UX best practices._
 
-_This article was originally written for the [platformOS Blog](https://www.platform-os.com/blog/post/building-our-documentation-site-on-platformos-part-2-content-production-and-layouts)._
+_This article was originally written for the [platformOS Blog](https://www.platformos.com/blog/post/building-our-documentation-site-on-platformos-part-2-content-production-and-layouts)._
 
 {% include sign-up.html %}