You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: _learn/02-jekyll-ruby-gh-pages.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ image:
7
7
caption: "Screenshot using Minimal Mistakes theme"
8
8
---
9
9
10
-
Jekyll is a Static Site Generator that typically accepts [Markdown](http://commonmark.org/help/) for authoring. [Jekyll](https://jekyllrb.com/) has its own documentation site and a [Quickstart](https://jekyllrb.com/docs/). To prepare your environment to build Jekyll sites locally, follow the instructions for either Windows or MacOS.
10
+
Jekyll is a Static Site Generator that typically accepts [Markdown](https://commonmark.org/help/) for authoring. [Jekyll](https://jekyllrb.com/) has its own documentation site and a [Quickstart](https://jekyllrb.com/docs/). To prepare your environment to build Jekyll sites locally, follow the instructions for either Windows or MacOS.
11
11
12
12
## Set up Ruby and Jekyll on Windows with Docker
13
13
@@ -193,7 +193,7 @@ Once you've prepared your environment, you can build locally and review the site
Copy file name to clipboardExpand all lines: _posts/articles/2017-03-18-pantheon-case-study.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -61,7 +61,7 @@ It depends. We migrated a lot of content because it didn’t make sense to start
61
61
62
62
Pantheon uses CircleCI for continuous integration which builds all commits pushed to GitHub then tests and deploys changes to either a staging environment or to production. Deployments to production occur via rsync after tests have run successfully. If any test fails (broken link, performance regression, etc.) The build will fail on CircleCI and the deployment to production is skipped until a passing build occurs. Branches other than our default branch get deployed to isolated cloud development environments for staging with unique and publicly accessible URLs. Deployments to staging environments happen before the test suite is run to help debug issues and/or failures. Once builds have been deployed to a staging environment, a comment is created on the commit in GitHub with a link to the changes for quick and easy peer review. Once a feature branch has been merged into the default, the associated staging environment is automatically deleted along with the branch. The automation procedures are scripted in Bash and configured in the `circle.yml` file within the project’s root directory. The staging environments are created using Pantheon’s command line tool, [Terminus](https://pantheon.io/docs/terminus/), and our [Multidev](https://pantheon.io/features/multidev-cloud-environments) feature.
63
63
64
-
This workflow is not available to forks for security reasons. For details, see CircleCI’s documentation: [Security Implications of Running Builds for Pull Requests from Forks](https://circleci.com/docs/fork-pr-builds/#security-implications-of-running-builds-for-pull-requests-from-forks).
64
+
As of March 2017, this workflow was not available to forks for security reasons. As of May 2019, [CircleCI’s documentation](https://circleci.com/docs/2.0/gh-bb-integration/) indicates there's a setting for PRs created from forked repos.
65
65
66
66
#### Are there any questions you wish you had asked before using GitHub for docs?
Copy file name to clipboardExpand all lines: _posts/articles/2017-04-04-balsamiq-case-study-part-1.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -23,11 +23,11 @@ The three parts cover documenting multiple product versions, [adding play and pa
23
23
24
24
## Background
25
25
26
-
A year and a half ago [we ditched our flaky content management system](https://blog.balsamiq.com/new-documentation-site/) and converted our documentation site over to a "docs like code" system using [Hugo](http://gohugo.io/), [Gulp](http://gulpjs.com/), and [GitHub](https://github.com/), with content written in Markdown. It was a long process and we were happy just to see it up and running.
26
+
A year and a half ago [we ditched our flaky content management system](https://blog.balsamiq.com/new-documentation-site/) and converted our documentation site over to a "docs like code" system using [Hugo](https://gohugo.io/), [Gulp](https://gulpjs.com/), and [GitHub](https://github.com/), with content written in Markdown. It was a long process and we were happy just to see it up and running.
27
27
28
28
After the dust settled, we started imagining what we wanted for the next version, and realized that the system we had built had limitations that we would have to overcome. This is a story of three challenges and how we solved them.
29
29
30
-
***Note:****The code in this article is specific to [Hugo](http://gohugo.io/), the static site generator we use, but should be adaptable to other static site generators.*
30
+
***Note:****The code in this article is specific to [Hugo](https://gohugo.io/), the static site generator we use, but should be adaptable to other static site generators.*
@@ -41,7 +41,7 @@ The majority of our documentation is how to use one of the two core wireframe ed
41
41
42
42
For historical reasons, most of the common documentation is in the Desktop version docs. If you used our product on a different platform, you had to know to go to the Desktop docs.
43
43
44
-
This is what the content folder in our [GitHub repo](https://github.com/balsamiq/docs.balsamiq.com) looked like, which meant that a lot of customers had this experience:
44
+
This is what the content folder in our GitHub repo looked like, which meant that a lot of customers had this experience:
Copy file name to clipboardExpand all lines: _posts/articles/2017-04-09-balsamiq-case-study-part-2.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,7 +19,7 @@ After learning about [documenting multiple product versions with a static site g
19
19
20
20
## Background
21
21
22
-
[Balsamiq set up a new documentation site](https://blog.balsamiq.com/new-documentation-site/) about a year and a half ago. We converted our old, flaky documentation system over to a "docs like code" system using [Hugo](http://gohugo.io/), [Gulp](http://gulpjs.com/), and [GitHub](https://github.com/), with content written in Markdown. The conversion took a while, so in the end we were pleased simply to get working.
22
+
[Balsamiq set up a new documentation site](https://blog.balsamiq.com/new-documentation-site/) about a year and a half ago. We converted our old, flaky documentation system over to a "docs like code" system using [Hugo](https://gohugo.io/), [Gulp](https://gulpjs.com/), and [GitHub](https://github.com/), with content written in Markdown. The conversion took a while, so in the end we were pleased simply to get working.
23
23
24
24
Once it was part of our daily workflow, and we could begin to look to the future, we started envisioning the next version. In doing so, we recognized the limitations and looked for solutions that kept writers writing and readers reading. This series tells the tale of three of these problem areas and how we solved the challenges.
Copy file name to clipboardExpand all lines: _posts/articles/2017-06-05-free-open-source-api-doc-tools.md
+6-4Lines changed: 6 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -121,7 +121,7 @@ Besides the ones detailed above, there are plenty of different open source API d
121
121
-[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.
122
122
-[Whiteboard](https://github.com/mpociot/whiteboard): A NodeJS based project started from Slate.
123
123
-[apiDoc](http://apidocjs.com/): Inline documentation for RESTful web APIs, that creates a documentation from API annotations in your source code.
124
-
-[CUUBEZ API Visualizer](http://apivisualizer.cuubez.com/): 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.
124
+
-[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.
125
125
-[Apidox](http://apidox.net/): XML powered live interactive API documentation and browsing for RESTful APIs.
126
126
-[Carte](https://github.com/Wiredcraft/carte): A simple Jekyll based documentation website for APIs. Designed as a boilerplate to build your own documentation, heavily inspired by Swagger and I/O docs.
127
127
-[Docbox](https://github.com/tmcw/docbox): A responsive website generated from Markdown documentation content. It’s dynamically updated with React.
@@ -137,9 +137,11 @@ Although very handy, API documentation generators are not the only way to render
137
137
138
138
A couple of documentation tools you can check out:
139
139
140
+
<!-- No longer available as of May 2019.
140
141
- [Dexy](http://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.
142
+
-->
141
143
-[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.
142
-
-[Doxygen](http://www.stack.nl/~dimitri/doxygen/): 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.
144
+
-[Doxygen](http://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.
143
145
144
146
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.
0 commit comments