Merge pull request #11 from kelshmo/test-new-getting-started

Test new getting started

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+
+name: Bug Report
+about: Create a bug report to help us improve synapseDocs
+title: "BUG:"
+labels: "bug"
+
+---
+
+- [ ] I have checked the existing issues to confirm it has not already been reported.
+
+- [ ] I have confirmed this bug exists on the latest version of [Synapse Documentation](https://docs.synapse.org/).
+
+
+---
+
+#### Problem Description
+
+[Explain **why** the current behaviour is a problem and why the proposed change is a better solution.]
+
+#### Proposed Change

.github/ISSUE_TEMPLATE/documentation_improvement.md

@@ -0,0 +1,21 @@
+---
+
+name: Documentation Improvement
+about: Report wrong or missing documentation
+title: "DOC:"
+labels: "enhancement"
+
+---
+
+#### Location of the Documentation
+
+[Provide the location of the documentation, e.g. "_articles/access_controls.md" or the URL of the documentation, e.g. "https://docs.synapse.org/articles/access_controls.html". Alternatively, let us know if it is missing!] 
+
+#### Problem
+
+[Provide a description of the documentation to be fixed or improved.]
+
+#### Suggested Fix
+
+[Explain the suggested fix and **why** it is an improvement.]
+

.github/ISSUE_TEMPLATE/submit_question.md

@@ -0,0 +1,16 @@
+---
+
+name: Submit Question
+about: Ask a general question about Synapse
+title: "QST:"
+label: "help wanted"
+
+---
+
+- [ ] I have looked through [Synapse Documentation](https://docs.synapse.org/) for my question.
+
+---
+
+#### Question about synapseDocs
+
+Ask us about [Synapse](https://www.synapse.org/) or [Synapse Documentation](https://docs.synapse.org/).

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,6 @@
+- [ ] Fixes #xxxx (Link Github Issue if appropriate?)
+- [ ] If you are creating a page, did you follow the instructions [here](https://github.com/Sage-Bionetworks/synapseDocs#creating-a-page)?
+- [ ] Did you follow the [style guide](https://github.com/Sage-Bionetworks/synapseDocs#style-guide)?
+testing-your-github-pages-site-locally-with-jekyll))?
+- [ ] Did you include a description of your changes or additions in this pull request?
+- [ ] (Optional) Did you examine your build locally (instructions [here](https://help.github.com/en/github/working-with-github-pages/))

README.md

@@ -17,19 +17,18 @@ Synapse Docs is generated using [Github Pages](https://pages.github.com/). Follo
 
 To build locally, follow the instructions found [here](https://help.github.com/en/articles/testing-your-github-pages-site-locally-with-jekyll). You will need Jekyll, Ruby, and the Ruby package manager, Bundler.
 
-
 Internal development can be performed by branching from `gh-pages` to your own feature branch, making changes, pushing the branch to this repository, and opening a pull request. Pull requests against the `gh-pages` branch require a review before merging.
+
 ### Categories
 
-Pages are described by categories. These are stored in a Jekyll collection at [_categories](_categories/). The content that describes each category is defined in a YAML header in a file in that directory. The categories avaiable for reference elsewhere are named as the file or as present in the 'name' field of the YAML header.
+Pages are described by categories. These are stored in a Jekyll collection at [_categories](_categories/). The architecture of this repo is described in the [Jekyll collection documentation](https://jekyllrb.com/docs/collections/).  The content that describes each category is defined in a YAML header in a file in that directory. The categories avaiable for reference elsewhere are named as the file or as present in the 'name' field of the YAML header.
 
 For example, if you want to create a page with a governance category, you would look in [_categories/governance.md](_categories/governance.md) in the 'name' field and use that value.
+
 ### Creating a page
 
 To create a page using the article layout, start by specifying at the very beginning the title, layout, excerpt, and category in the YAML front matter. The title and excerpt will show up in the article's user guide thumbnail and the category tag will be used to sort the article into its corresponding user guide tab. If no category is specified, it will default into the "How-To" tab. 
 
-
-
 Note that the front matter needs to be enclosed between three dashed lines to work properly.
 
 ```
@@ -75,6 +74,7 @@ To include new paragraphs, just add the `<br/>` tag within the content, like thi
 ```
 
 ### Adding a table
+
 To add a table, use Liquid to call on the markdown-table css class. Then use the standard markdown table format.
 ```
 {:.markdown-table}
@@ -85,15 +85,39 @@ To add a table, use Liquid to call on the markdown-table css class. Then use the
 ```
 
 ### Inserting an image
+
 Images can be inserted using either Markdown or HTML, it all depends on your preference. The examples below will display the same thing:
 ```
 ![alt text](/assets/images/image1.jpg)
 <img src="/assets/images/image1.jpg" alt="alt text">
 ```
 
 ### Inserting code 
+
 The docs may contain a high level overview of a feature, but should link to the [Python docs](https://python-docs.synapse.org/build/html/index.html) and [synapser](https://r-docs.synapse.org/articles/synapser.html) docs, pointing to the relevant anchor, for code examples. This is to ensure code is validated with the client release cycles. 
 
+### Inserting relative links
+
+A page may link to other pages within the documentation site. To do this, use a `link` Liquid tag to properly render the URL:
+
+```
+[link text]({{ site.baseurl }}{% link _articles/getting_started.md %})
+```
+
+If the link uses an anchor to jump to a specific part of the page, it must go outside the `link` tag:
+
+```
+[Annotations]({{ site.baseurl }}{% link _articles/annotation_and_query.md %}#adding-annotations)
+```
+
+### Linking to Synapse client documentation 
+
+Code examples in the documentation should be minimal. Preferably, links are provided to the Python, R, commandline and REST documentation. 
+- [r-docs.synapse.org](https://r-docs.synapse.org/)
+- [python-docs.synapse.org](https://python-docs.synapse.org/)
+    - [command line client documented in Python docs](https://python-docs.synapse.org/build/html/CommandLineClient.html?highlight=command%20line) 
+- [rest-docs.synapse.org/rest](http://rest-docs.synapse.org/rest/)
+
 ## License
 
 Distributed under the Eclipse Public License, the same as Clojure.

_articles/access_controls.md

@@ -6,7 +6,7 @@ category: governance
 order: 2
 ---
 
-Synapse has two ways to control who can access your content. Sharing Settings determine _who_ can access content, and is akin to individual or group (team) permissions. Conditions for Use determine _how_ data can be used by those users who have been granted access. All content in Synapse has Sharing Settings but not all content has Conditions for Use. See the [Sharing Settings](sharing_settings.md) article for information about those settings - this article covers conditions for use only.
+Synapse has two ways to control who can access your content. Sharing Settings determine _who_ can access content, and is akin to individual or group (team) permissions. Conditions for Use determine _how_ data can be used by those users who have been granted access. All content in Synapse has Sharing Settings but not all content has Conditions for Use. See the [Sharing Settings]({{ site.baseurl }}{% link _articles/sharing_settings.md %}) article for information about those settings - this article covers conditions for use only.
 
 <a name="conditions-for-use"></a>
 

_articles/accounts_certified_users_and_profile_validation.md

@@ -26,7 +26,7 @@ The table below summarizes the user privileges for each level.
 
 ## User Responsibilities
 
-You are solely responsible for your actions on Synapse. You are required to abide by the [Synapse Terms and Conditions of Use](https://s3.amazonaws.com/static.synapse.org/governance/SageBionetworksSynapseTermsandConditionsofUse.pdf?v=4) and all policies and principles described in the [Synapse governance documents](governance.md). We strongly encourage you to familiarize yourself with these documents. Please contact the Synapse Access and Compliance Team (<mailto:[email protected]>) if you have any questions.
+You are solely responsible for your actions on Synapse. You are required to abide by the [Synapse Terms and Conditions of Use](https://s3.amazonaws.com/static.synapse.org/governance/SageBionetworksSynapseTermsandConditionsofUse.pdf?v=4) and all policies and principles described in the [Synapse governance documents]({{ site.baseurl }}{% link _articles/governance.md %}). We strongly encourage you to familiarize yourself with these documents. Please contact the Synapse Access and Compliance Team (<mailto:[email protected]>) if you have any questions.
 
 {% include important.html content="By using Synapse you consent to all Synapse governance policies and procedures." %}
 
@@ -69,11 +69,11 @@ Go to the settings area of your [Synapse profile homepage](https://www.synapse.o
 
 1. Confirm your user profile is complete including **your full name, current affiliation, and city/country.**
 1. Link to your ORCID profile. **Make sure your profile is public and populate it with at least one piece of information about yourself in addition to your name.**
-1. Physically sign (in ink), initial, and submit the Synapse [Oath](../assets/other/oath.md)
+1. Physically sign (in ink), initial, and submit the Synapse [Oath]({{ site.baseurl }}{% link assets/other/oath.md %})
 1. Submit recent (current within the past month) identity attestation documentation. Acceptable forms of documentation, in English, are:
 
-* A letter from a signing official on letterhead attesting to your identity. _Please note that you can not serve as your own signing official_ ([template here](../assets/other/signing_official_template.md)) OR
-* A notarized letter attesting to your identity ([template here](../assets/other/notarized_letter_template.md)) OR
+* A letter from a signing official on letterhead attesting to your identity. _Please note that you can not serve as your own signing official_ ([template here]({{ site.baseurl }}{% link assets/other/signing_official_template.md %})) OR
+* A notarized letter attesting to your identity ([template here]({{ site.baseurl }}{% link assets/other/notarized_letter_template.md %})) OR
 * A copy of your professional license (e.g., a photocopy of your medical license)
 _Please note that a copy of a work or university identification badge is not an accepted form of identity attestation documentation._
 
@@ -83,7 +83,7 @@ You will receive a notification email when your profile has been validated and a
 
 Acceptable forms of documentation, in English, are:
 
-* A letter from a signing official on letterhead attesting to your identity. _Please note that you can not serve as your own signing official_ ([template here](../assets/other/signing_official_template.md)) OR
-* A notarized letter attesting to your identity ([template here](../assets/other/notarized_letter_template.md)) OR
+* A letter from a signing official on letterhead attesting to your identity. _Please note that you can not serve as your own signing official_ ([template here]({{ site.baseurl }}{% link assets/other/signing_official_template.md %})) OR
+* A notarized letter attesting to your identity ([template here]({{ site.baseurl }}{% link assets/other/notarized_letter_template.md %})) OR
 * A copy of your professional license (e.g., a photocopy of your medical license)
 _Please note that a copy of a work or university identification badge is not an accepted form of identity attestation documentation._

_articles/annotation_and_query.md

@@ -24,15 +24,15 @@ Annotations can be one of four types:
 
 ## How to Assign Annotations
 
-Annotations may be added when initially uploading a file or at a later date. This can be done using the command line client, the [Python client](https://python-docs.synapse.org/build/html/Views.html#updating-annotations-using-view), the [R client](https://r-docs.synapse.org/articles/views.html#updating-annotations-using-view), or from the web. Using the programmatic clients facilitates batch and automated population of annotations across many files. The web client can be used to bulk update many files using [file views](views.md).
+Annotations may be added when initially uploading a file or at a later date. This can be done using the command line client, the [Python client](https://python-docs.synapse.org/build/html/Views.html#updating-annotations-using-view), the [R client](https://r-docs.synapse.org/articles/views.html#updating-annotations-using-view), or from the web. Using the programmatic clients facilitates batch and automated population of annotations across many files. The web client can be used to bulk update many files using [file views]({{ site.baseurl }}{% link _articles/views.md %}).
 
 ### Adding Annotations
 
 To add annotations on a single entity through the web client, click the **Annotations** button in the upper right corner on a Project, Folder, or File page.
 
 ![Annotation web location](../assets/images/webAnnotation.png)
 
-To add annotations on multiple files, please refer to our Synapse in Practice article [Managing Custom Metadata at Scale](managing_custom_metadata_at_scale.md) for a tutorial on how to do this efficiently and effectively leveraging [file views](views.md).
+To add annotations on multiple files, please refer to our Synapse in Practice article [Managing Custom Metadata at Scale]({{ site.baseurl }}{% link _articles/managing_custom_metadata_at_scale.md %}) for a tutorial on how to do this efficiently and effectively leveraging [file views]({{ site.baseurl }}{% link _articles/views.md %}).
 
 ##### Command line
 
@@ -65,7 +65,7 @@ Click **File Tools**, **Annotations** and **Edit** to add, delete, or modify ann
 
 ![Annotation editor](../assets/images/annotationsDetail.png)
 
-To add annotations on multiple files, please refer to our Synapse in Practice article [Managing Custom Metadata at Scale](managing_custom_metadata_at_scale.md) for a tutorial on how to do this efficiently and effectively leveraging [file views](views.md).
+To add annotations on multiple files, please refer to our Synapse in Practice article [Managing Custom Metadata at Scale]({{ site.baseurl }}{% link _articles/managing_custom_metadata_at_scale.md %}) for a tutorial on how to do this efficiently and effectively leveraging [file views]({{ site.baseurl }}{% link _articles/views.md %}).
 
 ##### Command line
 
@@ -133,7 +133,7 @@ SELECT * FROM syn123456 WHERE "id" = 'syn00012'
 
 ### Finding Files in a Specific Project
 
-To find all files in a specific Project, create a View in the web client. For example, if you'd like to see all files in a Project, navigate to your project and then the **Tables** tab. From there, click **Tables Tools** and **Add File View**. Click **Add container** and **Enter Synapse Id** to create a tabluar file view that contains every file in the project, which you can now query. Importantly, if you want to later query on annotations, you must select **Add All Annotations**. For a more in-depth look at this feature, please read our articles on [File Views](views.md).
+To find all files in a specific Project, create a View in the web client. For example, if you'd like to see all files in a Project, navigate to your project and then the **Tables** tab. From there, click **Tables Tools** and **Add File View**. Click **Add container** and **Enter Synapse Id** to create a tabluar file view that contains every file in the project, which you can now query. Importantly, if you want to later query on annotations, you must select **Add All Annotations**. For a more in-depth look at this feature, please read our articles on [File Views]({{ site.baseurl }}{% link _articles/views.md %}).
 
 ### Listing Files in a Specific Folder
 
@@ -213,4 +213,4 @@ SELECT * FROM syn123 where "chemicalStructure" = '4''-chemical'
 
 # See Also
 
-[Downloading Data](downloading_data.md), [Tables](tables.md)
+[Downloading Data]({{ site.baseurl }}{% link _articles/downloading_data.md %}), [Tables]({{ site.baseurl }}{% link _articles/tables.md %})

_articles/api_documentation.md

@@ -4,6 +4,7 @@ description: Technical documentation for interacting with Synapse using R, Pytho
 excerpt: Technical documentation for interacting with Synapse using R, Python, command line, and the REST API.
 layout: index
 category: API-client
+order: 3
 ---
 
 

_articles/article_index.md

@@ -1,7 +1,7 @@
 ---
-title: Articles Index
+title: Articles
 layout: index
-description: All documentation articles about Synapse.
+description: An index of articles available about Synapse.
 ---
 
 <div class="col-xs-12 col-md-12 col-lg-12" id="subjects">