Skip to content

Latest commit

 

History

History
382 lines (253 loc) · 13.2 KB

CONTRIBUTING-TECHNICAL-GUIDE.md

File metadata and controls

382 lines (253 loc) · 13.2 KB

Tyk Documentation

Contains the Tyk Documentation source.

How to Contribute

We recommend contributing in the following way:

  • Fork this repository
  • Clone the forked repository on your machine
  • Create a remote branch, e.g git remote add upstream https://github.com/TykTechnologies/tyk-docs.git
  • Fetch from the remote branch git fetch upstream
  • Rebase your branch with the latest remote branch content git rebase upstream/master

The following guide briefly explains how to work with Hugo, you would then need push to your forked repository and then create a Pull Request to Tyk's master branch.

How to Use

Our Documentation is constructed using Hugo.

Getting Started

  1. Clone this repository
  2. Navigate to the project directory

Use with Docker

  1. Docker
  2. Run docker-compose up from the project directory

Use with Hugo

  1. Install Hugo v0.96.0 or greater
  2. Run hugo server --theme=tykio --buildDrafts --enableGitInfo from the tyk-docs/tyk-docs directory

Go to http://localhost:1313/docs/nightly/ to view the docs locally

Adding and Editing Content

The docs content lives in tyk-docs/content.

Add a new Section

  1. Add a new folder in within the tyk-docs/tyk-docs/content/ Directory. For example new-section
  2. Within your new folder create a markdown file with the following command from your terminal - hugo new. For the above example you would run hugo new /new-section/new-section.md. This file will be converted to the equivalent of an index.html file.
  3. You can then create other markdown files within that directory, that you can name as you want.

readme-example

Front Matter

For each new file created via hugo new, the following YAML formated Front Matter is added:

---
title: "New Section"
date: 2021-02-10
tags: [""]
description: ""
menu: "main"
weight: 0
---

**Insert Lead paragraph here.**
  • title is taken from the name of the markdown file created
  • date is auto populated in a year-month-day format
  • tags are used to create meta keywords in the HTML output, and are added in the following format - tags: ["tag 1", "tag 2", "tag 3"]
  • description is used for the meta description in the HTML output
  • menu is used to place the page in the correct place within the navigation hierarchy. By default a new page is assigned to the root level (main)
  • weight is used to order pages within a section of the menu with 0 being the top level page within a section.

You can create a dynamic, nested navigation hierarchy simply by changing the parent field to the name of the parent page. Note, these names must be unique.

Example front matter for a page:

---
title: "Test"
date: 2021-02-10
tags: ["Tyk", "advanced-configuration", "Dashboard"]
description: "Testing the description and tagging functionality in Tyk"
menu:
  main:
    parent: "Advanced Configuration"
weight: 10
---

Content

The content itself is just markdown that follows the front matter block. When you add and edit new content, Hugo should auto-reload and you should be able to see the changes live in your browser (if not, refresh). Sometimes Hugo gets confused and you may need to re-run it.

Links

All links should be defined with ref function, which ensure that link will be correct, and will never break docs. As value you specify path the file inside of "content" folder, but because our URL structure synced with file structure, it will be same as URL path. Example:

[Link title]({{< ref "apim/open-source" >}})

Images

All images should be uploaded to assets/img folder (do not confuse it with static/img). All images should be defined using img tag. Example:

{{< img src="/img/docker.png" alt="Docker" width="500px" >}}

src argument is required, rest are optional.

Shortcodes

Various shortcodes are used within the Tyk documentation.

Grid shortcode

You can find 3 sizes of grid layouts. This is used in conjunction with the badges shortcode

  1. grid
  2. mid
  3. big

Grid

{{< grid >}}

Content goes here

{{< /grid >}}

Mid

{{< grid type="mid" >}}

Content goes here

{{< /grid >}}

Big

{{< grid type="big">}}

Content goes here

{{< /grid >}}

Badge

The badge shortcode can be used in differing ways to populate the 3 grid types. We have used these on the default docs landing page, and the Tyk Cloud landing page. The examples are from the default landing page.

Quickstart Installation Badge

## Quickstart Installation

{{< grid >}}

{{< badge read="15 mins" href="/docs/tyk-cloud/" image="/docs/img/tyk-cloud.svg" >}}
Sign up for our new, next level **SaaS** product. 
{{< /badge >}}

{{< badge read="15 mins" href="/docs/getting-started/with-tyk-on-premises/installation/on-aws/" image="/docs/img/aws.png">}}
Install our **On-Premises** product on AWS. 
{{< /badge >}}


{{< badge read="10 mins" href="/docs/getting-started/installation/with-tyk-on-premises/docker/" image="/docs/img/docker.png">}}
Install our **On-Premises** product with Docker. 
{{< /badge >}}

{{< badge read="10 mins" href="/docs/getting-started/installation/with-tyk-on-premises/kubernetes/" image="/docs/img/k8s.png">}}
Install our **On-Premises** product with Kubernetes. 
{{< /badge >}}

{{< /grid >}}

image

Tyk Stack Badge

This badge uses the mid grid shortcode type.

## The Tyk Stack

{{< grid type="mid" >}}

{{< badge href="/docs/getting-started/tyk-components/gateway/" image="/docs/img/diagram.png" imageStyle="height:150px" >}}
**Tyk Gateway**

The primary application for Community Edition users and Pro users alike, the Tyk Open Source API Gateway does all the heavy lifting of actually managing your requests.
{{< /badge >}}

{{< badge href="/docs/getting-started/tyk-components/dashboard/" image="/docs/img/diagram.png" imageStyle="height:150px" >}}
**Tyk Dashboard**

The Tyk Dashboard is the visual GUI and analytics platform for Tyk. It provides an easy-to-use management interface for managing a Tyk installation as well as clear and granular analytics.
{{< /badge >}}

{{< badge href="/docs/getting-started/tyk-components/pump/" image="/docs/img/diagram.png" imageStyle="height:150px" >}}
**Tyk Pump**

The Tyk Pump is our open source analytics purger that moves the data generated by your Tyk nodes to any back-end. It is primarily used to display your analytics data in the Tyk Dashboard.
{{< /badge >}}

{{< badge href="/docs/getting-started/tyk-components/developer-portal/" image="/docs/img/diagram.png" imageStyle="height:150px" >}}
**Tyk Developer Portal**

The Tyk Developer Portal is a small CMS-like system that enables you to expose a facade of your APIs and then allow third-party developers to register and use your APIs.
{{< /badge >}}

{{< badge href="/docs/getting-started/tyk-components/mdcb/" image="/docs/img/diagram.png" imageStyle="height:150px" >}}
**MDCB**

The Multi Data Centre Bridge allows for centralised management of multiple independent Tyk clusters and the seamless transition of APIs between environments, availability zones and segmented nodes.
{{< /badge >}}

{{< badge href="/docs/getting-started/tyk-components/identity-broker/" image="/docs/img/diagram.png" imageStyle="height:150px" >}}
**Identity Broker**

The Tyk Identity Broker (TIB) is a microservice portal that provides a bridge between various Identity Management Systems and your Tyk installation.
{{< /badge >}}

{{< /grid >}}

image

Features Badge

## Feature Setups

{{< grid >}}

{{< badge title="Security" href="/docs/basic-config-and-security/security/tls-and-ssl/" >}}
#### TLS & SSL

TLS connections are supported for all Tyk components
{{< /badge >}}

{{< badge title="Dashboard" href="/docs/tyk-dashboard-analytics/" >}}
#### Analytics

Learn how to segment and view your API traffic and activity
{{< /badge >}}

{{< badge title="New in v3.0" href="/docs/graphql/" >}}
#### GraphQL

Tyk supports GraphQL natively. Proxy to existing service or build it from scratch.
{{< /badge >}}

{{< badge title="Integration" href="/docs/advanced-configuration/integrate/sso/" >}}
#### Single Sign On

Log into dashboard and portal with your existing IDP.
{{< /badge >}}

{{< /grid >}}

image

Resources Badge

This uses the big grid shortcode type.

## Resources

{{< grid type="big" next="/adasd">}}

{{< badge title="Tyk Cloud" href="/asd" image="/docs/img/blog_placeholder.png" read="10 mins" >}}
#### Feature

Lorem ipsum Dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt.
{{< /badge >}}

{{< badge title="API Manager" href="/asd" read="10 mins" >}}
## Lorem ipsum Dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt.
{{< /badge >}}

{{< badge title="Tyk Gateway" href="/asd" read="10 mins" image="/docs/img/blog_placeholder.png" >}}
#### Feature

Lorem ipsum Dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt.
{{< /badge >}}

{{< badge title="API Manager" href="/asd" read="10 mins" image="/docs/img/blog_placeholder.png" >}}
#### Feature

Lorem ipsum Dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt.
{{< /badge >}}

{{< badge title="API Manager" href="/asd" read="10 mins" image="/docs/img/blog_placeholder.png" >}}
#### Feature

Lorem ipsum Dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt.
{{< /badge >}}

{{< /grid >}}

image

Buttons

We have 3 button types that can be used in conjuction with the Grid layout shortcode. These all aligh centrally and use the Tyk colour palette.

{{< button href="/docs/basic-config-and-security/" color="black" content="More Tyk Configuration" >}}

{{< button href="/docs/getting-started/key-concepts/" color="red" content="Tyk Concepts" >}}

{{< button href="/docs/getting-started/installation/" color="green" content="All installation options" >}}

image image image

Note and Warning shortcodes

Use these instead of the usual markdown blockquote style.

Note

{{< note success >}}
**Note**
  
You need to have at least one Edge Gateway with a *Deployed* status connected to your Control Plane.
{{< /note >}}

image

Warning

{{< warning success >}}
**Warning**
  
We recommend you restrict your IAM user as much as possible before sharing the credentials with any 3rd party, including Tyk Cloud. See [IAM User Permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html) for more details.
{{< /warning >}}

image

See the Hugo Docs for other built in shortcodes.

Tooltips shortcode

You can add tooltips by using the following shortcode:

{{< tooltip >}}some link text definition{{< definition >}} the tooltip text to display{{< /definition >}}{{< /tooltip >}}

tooltip-demo

License

Tyk is released under the MPL v2.0 please see the license file for a full version of the license.

The Pipeline

When you create a PR in this repository:

  1. CI pipeline will run tests (Hugo and Netlify).

image

  1. Netlify will create a version of the website from your PR and provide you with a link:
  • Don't forget to add /docs/nighly to the URL.

image

  1. Verifing your changes in the Netlify build: