diff --git a/tyk-docs/content/developer-support/contributing.md b/tyk-docs/content/developer-support/contributing.md index eb132f2e1f..c787271323 100644 --- a/tyk-docs/content/developer-support/contributing.md +++ b/tyk-docs/content/developer-support/contributing.md @@ -5,20 +5,13 @@ tags: [ "Contributing", "Documentation", "Community" ] description: "How to contribute to Tyk documentation" aliases: - /contribute + - /ui-examples/feature-cards + - /ui-examples/test-pill-label + - /ui-examples/youtube-video-embed --- This section provides resources and guidance for contributors to Tyk's documentation. Whether you're fixing a typo, adding new content, or helping improve our documentation standards, you'll find the tools and guidelines you need here. -## What this section covers - -This contribution section includes: - -- **[Inclusive naming]({{< ref "developer-support/documentation-projects/inclusive-naming" >}})** - Information about Tyk's inclusive language initiative and the work done to update documentation terminology -- **UI component examples** - Documentation and examples for using shortcodes in our documentation system: - - **[Pill label shortcode]({{< ref "ui-examples/test-pill-label" >}})** - For labeling content with edition indicators (Enterprise, Cloud, Lab Release, etc.) - - **[Feature cards shortcode]({{< ref "ui-examples/feature-cards" >}})** - For creating responsive feature highlight grids - - **[YouTube video embed shortcode]({{< ref "ui-examples/youtube-video-embed" >}})** - For embedding videos with proper styling and SEO - ## How to contribute to our docs We appreciate any form of engagement and contribution to our documentation. You can contribute in several ways: @@ -36,5 +29,4 @@ For detailed contribution guidelines, including pull request requirements, codin ### Technical guidance -Our docs are compiled using the [Hugo static site generator](https://gohugo.io/). For detailed technical guidance on creating and updating documentation pages, see the [technical guide](https://github.com/TykTechnologies/tyk-docs/blob/master/CONTRIBUTING-TECHNICAL-GUIDE.md) referenced in our [CONTRIBUTING.md](https://github.com/TykTechnologies/tyk-docs/blob/master/CONTRIBUTING.md) file. - +Our docs uses [Mintlify](https://mintlify.com/). For detailed technical guidance on creating and updating documentation pages, see the [technical guide]({{< ref "developer-support/contribution-guides" >}}). diff --git a/tyk-docs/content/developer-support/contribution-guides.md b/tyk-docs/content/developer-support/contribution-guides.md new file mode 100644 index 0000000000..cafdbe98ff --- /dev/null +++ b/tyk-docs/content/developer-support/contribution-guides.md @@ -0,0 +1,259 @@ +--- +title: "Contributing Guides" +description: "Guide to releasing Tyk documentation" +tags: ["Guides", "Contribution to Tyk", "Open source contribution guide"] +--- + +## Introduction + +Tyk documentation is built using [Mintlify](https://mintlify.com/), a platform that allows us to create, manage and publish our documentation. +This page provides an overview and guidelines to contributing to Tyk documentation, including setting up dev environment locally, creating new content, and utilize Mintlify's [UI objects](https://mintlify.com/docs/text). + +## Prerequisites - applys to all flows and tasks + +- You’ve set up the Tyk Docs local environment as described in the [Getting Started](#getting-started---running-mintlify-locally) section. +- You have a basic understanding of [Page Structure](https://mintlify.com/docs/pages) and [Navigation](https://mintlify.com/docs/navigation) in Mintlify. +- You’re familiar with Git and Markdown syntax. + +## Common steps for every task +- Any update requires a PR +- Please label your PR with the versions you want it to be added to +- Please assign a reviewer that is also a stakeholder who can sign off the change + +## Getting Started - Running Mintlify locally + +This secion provides instructions for setting up your local environment to work with Tyk documentation using Mintlify. + +1. **Install Mintlify CLI globally**: + ```bash + npm install -g mint + ``` +2. **Clone the Tyk Docs repository**: + ```bash + git clone https://github.com/TykTechnologies/tyk-docs.git && cd tyk-docs + ``` + + For external contributions, you will need to fork the Tyk docs repository and clone your fork: + ```bash + git clone + cd tyk-docs + ``` + +3. **Start the Mintlify development server**: + ```bash + mint dev + ``` +4. Open your browser and go to `http://localhost:3000` to view the documentation. + +## Creating a New Page + +To add a new page to the Tyk documentation, follow the steps below. + +1. **Switch to the `main` branch and pull the latest changes:** + + ```bash + git checkout main + git pull origin main + ``` + +2. **Create a new branch:** + + ```bash + git checkout -b + ``` + +3. **Create the new page:** + + The content is organized into folders under the root directory, reflecting the website's navigation structure (tabs, groups, etc.). Choose the appropriate folder for your new page. + + * Create a new `.mdx` file for the page. For example, for a page titled “API Versioning” you might create a file named `api-versioning.mdx`. + * Add [front matter](https://mintlify.com/docs/pages#frontmatter) to the top of the file. This is a YAML block containing metadata like the title, description, and tags. + + **Example front matter:** + + ```mdx + --- + title: "API Versioning" + description: "Create and manage multiple versions of an API" + sidebarTitle: "API Versioning" + tags: ['API versioning', 'version', 'Tyk Classic', 'Tyk OAS', 'API', 'versioning'] + --- + + + ``` + + * Write your content using Markdown. You can also use Mintlify UI components (e.g., accordions, callouts, code blocks) to improve readability and user experience. + +4. **Update `docs.json`:** + + To make your new page appear in the navigation, update the `docs.json` file in the root directory. + + **Example**: Adding a new page under the *"API Management"* tab in the *"Overview"* group. + + ```json + { + ... + "navigation": { + "tabs": [ + { + "tab": "API Management", + "groups": [ + { + "group": "Overview", + "pages": [ + "tyk-overview", + "tyk-components", + "apim", + "api-versioning" // New page added here + ] + } + ] + } + ] + } + ... + } + ``` + +5. **Commit and push your changes:** + + ```bash + git add -A + git commit -m "Add new page: " + git push origin + ``` + +6. **Create a pull request** on GitHub to merge your changes into `main`. + + Once the PR is opened, a series of automated checks will run: + + * Link Check: Mintlify checks for broken internal links. + * Spell Check: A vale-spellcheck ensures content quality. + * Documentation Validation: A custom script checks for things like missing images and redirect conflicts. + +7. **Preview your changes** using the link provided by Mintlify before merging. + + **For Contributors Outside Tyk:** A Tyk team member will need to approve the Mintlify CI build for your pull request (PR). You will need to wait + until the CI status is green. + + **Locating Your Changes:** Since there's no search feature in this Mintlify build, you can find your changes by following these steps: + 1. **Copy the file path**: From the file path in GitHub, copy the path, excluding the `.md` file extension. + 2. **Construct the URL**: Append this copied path to the Mintlify URL after `/docs`. + 3. **Example**: To see the document at tyk-docs GitHub repository, copy `/tyk-self-managed/install` (omit `.md`) and add it after /docs/ in the Netlify URL, resulting in [https://branch-name.mintlify.app/docs/tyk-self-managed/install/](https://branch-name.mintlify.app/docs/tyk-self-managed/install/). + +8. **Merge to main (Updates Nightly)** + + Once the PR is reviewed, approved, and all checks pass, it can be merged into `main`. This automatically triggers a deployment, and your changes will go live on the Nightly version of the docs. + +9. **Backporting to Release Versions (Cherry-Picking)** + If your change needs to be included in a stable release (e.g., v5.9): + + 1. Go to your original, now-merged PR on GitHub. + 2. Add a label corresponding to the target version, for example, release-5.9. + 3. That's it! An automated bot (buger) will detect this label. + + The bot will: + + 1. Cherry-pick the commit from your original PR. + 2. Create a new PR with those changes, targeting the release-5.9 branch. + 3. Automatically merge this new PR once all checks pass. + + The merge into the `release-5.9` branch triggers the `main` deployment workflow, which rebuilds the `production` branch. Mintlify detects the update and deploys the changes to the live v5.9 documentation. + +## Updating an Existing Page + +To make changes to an existing page in the Tyk documentation, follow these steps: + +1. **Switch to the `main` branch and pull the latest changes:** + + ```bash + git checkout main + git pull origin main + ``` + +2. **Create a new branch:** + + ```bash + git checkout -b + ``` + +3. **Locate and edit the page:** + + * Navigate to the appropriate folder in the repository where the `.mdx` file for the page is located. + * Open the file and make your changes using Markdown syntax. You can enhance content using Mintlify UI components like callouts, accordions, tabs, and code blocks. + * If needed, update the front matter (e.g., `title`, `description`, `tags`) at the top of the file. + +4. **Preview your changes locally** to ensure formatting and layout appear as expected. + + ```bash + mintlify dev + ``` + +5. **Commit and push your changes:** + + ```bash + git add . + git commit -m "" + git push origin + ``` + +6. **Create a pull request** on GitHub to merge your branch into `main`. + +7. **Review the preview link** provided in the pull request to verify your changes before merging. + +## Deleting a Page + +To delete a page from the Tyk documentation, follow these steps: + +1. **Switch to the `main` branch and pull the latest changes:** + + ```bash + git checkout main + git pull origin main + ``` + +2. **Create a new branch from `main`:** + + ```bash + git checkout -b + ``` + +3. **Delete the relevant Markdown file** corresponding to the page you want to remove. + +4. **Update `docs.json`:** + + * Remove the entry for the deleted page from the `navigation` section. + * Add a redirect in the `redirect` section to point users to a relevant page. This prevents 404 errors when the deleted page is accessed. + +5. **Commit and push your changes:** + + ```bash + git add . + git commit -m "Delete page: - " + git push origin + ``` + +6. **Create a pull request** on GitHub to merge your branch into `main`. + +7. **Review the preview link** provided by Mintlify to ensure your changes appear as expected before merging. + +## Guide for UI features + +Apart from the basic markdown writing, Tyk documentation also support UI components like accordions, callouts, cards, expandables, tabs etc. These components help in enhance the documentation's usability and readability. + +Here's a table summarizing the UI features available for Tyk documentation: + +| Name | Description | +|------|-------------| +| [Code Blocks](https://mintlify.com/docs/code) | Display inline code and code blocks | +| [Accordions](https://mintlify.com/docs/components/accordions) | A dropdown component to toggle content visibility | +| [Callouts](https://mintlify.com/docs/components/callouts) | Use callouts to add eye-catching context to your content | +| [Cards](https://mintlify.com/docs/components/cards) | Highlight main points or links with customizable icons | +| [Expandables](https://mintlify.com/docs/components/expandables) | Toggle to display nested properties. | +| [Tabs](https://mintlify.com/docs/components/tabs) | Toggle content using the Tabs component | +| [Mermaid](https://mintlify.com/docs/components/mermaid-diagrams) | Display diagrams using Mermaid | +| [Steps](https://mintlify.com/docs/components/steps) | Sequence content using the Steps component | +| Snipptet | A custom component written by us. TODO | + +**Note:** The above components is a list of mostly used components in Tyk documentation. To see the complete list of components, refer to the [Mintlify documentation](https://docs.mintlify.com/docs/components). + diff --git a/tyk-docs/content/developer-support/release-guide.md b/tyk-docs/content/developer-support/release-guide.md new file mode 100644 index 0000000000..d8599df2b2 --- /dev/null +++ b/tyk-docs/content/developer-support/release-guide.md @@ -0,0 +1,186 @@ +--- +title: "Releasing Tyk Docs" +description: "Guide to releasing Tyk documentation" +tags: ["Authentication", "Authorization", "Tyk Authentication", "Tyk Authorization", "Secure APIs", "client"] +--- + +## Introduction + +This document outlines the process for releasing Tyk documentation, including patch and major/minor releases. It provides a clear understanding of the versioning system, the release workflow, and the steps required to ensure that documentation is up-to-date. + +## Types of Releases + +Tyk has two types of releases: + +1. **Patch Release:** e.g → 5.3.5, 5.3.6, 5.7.1, 5.7.2 + + A patch release includes bug fixes, small improvements, and security patches. It does not introduce any breaking changes. + +2. **Major/Minor Release:** e.g → 4.1, 4.2, 5.3, 5.4 + + A major or minor release includes new features, improvements, and potentially breaking changes. + +### Versioning in Tyk Docs + +Tyk Docs uses a versioning system that aligns with the Tyk components. The versioning follows the Semantic Versioning of Tyk [Gateway]({{< ref "developer-support/release-notes/gateway" >}}). + +## Understanding the Release Workflow + +Tyk Documentation is maintained in a [GitHub](https://github.com/TykTechnologies/tyk-docs) repository, and the release workflow is managed through branches. The following table outlines the special branches used in the Tyk Docs repository: + +| **Special Branches** | **Description** | **Docs URL** | +|---------------------------|-----------------|--------------| +| `main` | Holds docs for nightly build. | [tyk.io/docs/nighlty](https://tyk.io/docs/nighlty) | +| `release-x.y` | Holds docs for that specific version. For example, `release-5.7` holds docs for 5.7 and its patch versions (5.7.1, 5.7.2, etc.). | [tyk.io/docs/5.7](https://tyk.io/docs/5.7) | +| `production` | It acts as the single source of truth for the Mintlify platform. | [tyk.io/docs](https://tyk.io/docs) | + +### Production Branch + +* This is a special, **automated-only** branch. **No one should ever commit to it directly**. +* It acts as the single source of truth for the Mintlify platform. +* A GitHub Action (`deploy-docs.yml`) automatically builds this branch by: + 1. Cloning the main branch and all active release- branches. + 2. Organizing their content into versioned subfolders (e.g., /nightly/, /5.9/, /5.8/). + 3. Generating a unified `docs.json` navigation file that contains the structure for all versions. + Mintlify is connected only to this `production` branch and deploys any changes made to it. + +### Workflow + +All documentation content is always merged into the `main` branch first, and then the changes are made to the `release-x.y` branches as needed. + +```mermaid +graph TD; + + classDef repoStyle fill:#E1D5E7,stroke:#9673A6,stroke-width:2px,font-weight:bold; + classDef branchStyle fill:#D1E8FF,stroke:#007BFF,stroke-width:2px; + classDef urlStyle fill:#E2F0D9,stroke:#548235,stroke-width:2px; + classDef inputStyle fill:#FFF2CC,stroke:#D6B656,stroke-width:1px; + + Repo["GitHub: TykTechnologies/tyk-docs"] + class Repo repoStyle; + + NewContent["New Documentation Content / Changes"] + class NewContent inputStyle; + + subgraph SpecialBranches [Special Branches in Repository] + direction TB + main["main
Holds docs for nightly build"] + release_xy["release-x.y
(e.g., release-5.7)
Docs for specific version x.y
and its patch versions (x.y.z)"] + production["production
Holds the latest release docs"] + end + class main,release_xy,production branchStyle; + + subgraph PublishedURLs [Published Documentation URLs] + direction TB + url_nightly["tyk.io/docs/nightly"] + url_version["tyk.io/docs/x.y
(e.g., tyk.io/docs/5.7)"] + url_production["tyk.io/docs
(Live site / Latest production)"] + end + class url_nightly,url_version,url_production urlStyle; + + Repo --> main; + NewContent -- "Step 1. Content merged first into" --> main; + main -- "Step 2. Changes propagated/
backported (as needed)" --> release_xy; + release_xy -- "Step 3. Trigger Mintlify Production Build" --> production; + + main -. "Trigger Build" .-> production; + release_xy -. "Trigger Build" .-> production; + + production -. "Publishes to" .-> url_nightly; + production -. "Publishes to" .-> url_version; + production -. "Publishes to" .-> url_production; +``` + +### Previous Releases + +Tyk maintains [LTS versions]({{< ref "developer-support/release-types/long-term-support#current-lts-releases-timeline" >}}). During some releases, we need to update the LTS release alongside the latest version. For example, you may need to maintain both 5.7.2 (latest) and 5.3.2 (LTS). + +## Patch Release + +To release a patch version, we follow a simple process that involves merging the release notes and documentation PRs into the `main` and the specific release branch (e.g., `release-5.7`). + +### Pre-Requisites: + +Ensure the PRs for documentation, configuration, and release notes have already been approved. + +**Note:** For release notes, ensure that we have updated the Tyk component version on the [release summary page](https://tyk.io/docs/developer-support/release-notes/overview/) + +### Instructions + +1. **Deploy release:** + The PRs mentioned in the prerequisites can now be merged into the main and release branches (release-5.7) + +2. **Verify:** + After merging the PRs on the version branch (release-5.7), it typically takes 5 minutes for the changes to be reflected on the live website. Verify these changes after release. + +**Note:** We can also have a patch release for previous versions. For example, if the latest version is 5.7.2 and the new patch is 5.7.3, and a patch for LTS version 5.3.3 also needs to be released, then you will have to merge the PRs for both versions. + +## Major/Minor Release + +To release a major or minor version, we follow a series of steps to ensure that the documentation is updated, the latest version is deployed, and the previous versions are maintained correctly. The following steps outline the process: + +### Pre-Requisites: + +Ensure the PRs for documentation, configuration, and release notes have already been approved. + +**Note:** For release notes, ensure that we have updated the Tyk component version on the [release summary page](https://tyk.io/docs/developer-support/release-notes/overview/) + + +### Instructions + +1. **Create the New Release Branch** + From the main branch, create a new branch named release-X.Y (e.g., release-5.10). This branch will be used to maintain the documentation for the latest version. + +2. **Update the Branch Configuration** + In the main branch, edit the `branches-config.json` file. Add a new JSON object for the latest version. This configuration tells the build system how to handle the new version. + + * Set isLatest to true for the new release-5.10. + * Set isLatest to false for the previous latest version (e.g., release-5.9). + + **Example:** + + ```json + { + "branch": "release-5.10", + "isLatest": true, + "sourceFolder": "5.10-source", + "targetFolder": "5.10", + "label": "v5.10 (latest)" + } + ``` + +3. **Manually Trigger the Deployment Workflow** + + 1. Go to the "Actions" tab in the GitHub repository. + 2. Select the "Deploy Documentation" workflow. + 3. Click "Run workflow" and choose the `production` branch to run it against. + + This will rebuild the `production` branch, creating the new versioned folder and updating the site's navigation to include v5.10 as the latest version. + +4. **Deploy release:** + + The PRs mentioned in the prerequisites can now be merged into `main` and the latest release branch. + +7. **Update Postman Collections:**\ + We maintain a Postman collection for the following Tyk Components (Gateway, Dashboard, MDCB, and Developer Portal). After a major or minor release, we need to update the Postman collections. + + These instructions are for a single Tyk component and must be repeated for other components. + + 1. Download the Swagger from the docs website or the respective GitHub repository of the component. + + 2. In Postman, select the import option and drop the file you downloaded in the first step. + + 3. After the import, change the name. Refer to our previous collection name. + + 5. Add the `latest` prefix and remove the previous one. This ensures that the latest version is always displayed at the top. + +8. **Update the HubSpot Banner to indicate the new release of the old docs pages.**\ + **Description:** We use HubSpot to display a banner at the top of our docs page, which indicates that you are viewing old documentation and points to the latest version.\ + **Example:** [Sample Banner](https://tyk.io/docs/4.0/getting-started/key-concepts/graphql-subscriptions/). + + **Steps:** Update the HubSpot banner to indicate the new release. + +9. **Add a reference to release notes in Github Releases:**\ + **Description:** Developers usually refer to the GitHub release tags to view the changelog. These release tags should point to the release notes in the docs.\ + **Example:** \ + **Steps:** Modify the release tags of all components modified in a release.\ diff --git a/tyk-docs/content/ui-examples/feature-cards.md b/tyk-docs/content/ui-examples/feature-cards.md deleted file mode 100644 index 5d6aa3fa0c..0000000000 --- a/tyk-docs/content/ui-examples/feature-cards.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -date: 2025-04-28 -title: Feature Cards -tags: ["UI Examples", "Shortcodes", "Feature Cards"] -description: "Documentation for the feature-cards shortcode in Tyk. Learn how to display responsive feature cards with icons, titles, and descriptions." ---- - -The `feature-cards` shortcode creates a responsive grid of cards with icons, titles, and descriptions. This is ideal for presenting features or capabilities in a visually appealing way. - -## When to Use - -Use the feature-cards shortcode when you need to display a set of features or capabilities in a visually appealing grid format. It's particularly useful for: - -- Product feature highlights -- Service capabilities -- Key benefits lists -- Team member profiles -- Pricing plan comparisons - -The responsive design ensures your content looks great on all devices, from mobile phones to desktop screens. - -## Usage - -To use the feature cards shortcode in your markdown file, you need to specify a data file: - -```md -{{}} -``` - -## Configuration - -The feature cards are configured through JSON files located in the `data` directory. You must specify which data file to use with the `dataFile` parameter. Here's an example of how to structure a data file: - -```json -{ - "components": [ - { - "title": "Feature Title 1", - "icon": "🚀", - "description": "Description of the first feature." - }, - { - "title": "Feature Title 2", - "icon": "⚙️", - "description": "Description of the second feature." - }, - { - "title": "Feature Title 3", - "icon": "📊", - "description": "Description of the third feature." - }, - { - "title": "Feature Title 4", - "icon": "🔒", - "description": "Description of the fourth feature." - } - ] -} -``` - -### Data Structure - -Each feature card requires the following fields: - -- `title`: The title of the feature (displayed as a heading) -- `icon`: An emoji or character to use as the feature icon -- `description`: A short description of the feature - -Optionally, you can include: - -- `path`: A URL path for the "Learn More" button -- `button_text`: The text to display on the button (defaults to "Learn More") - -## Responsive Behavior - -The feature cards are fully responsive and will adjust based on screen size: - -- On mobile devices (width < 576px): 1 card per row -- On tablet devices (width 576px - 992px): 2 cards per row -- On desktop devices (width ≥ 992px): 4 cards per row - -## Styling - -The cards feature large, centered emoji icons with consistent styling: - -- White background -- Subtle shadow effect -- Rounded corners -- Centered content -- Consistent spacing -- Blue action buttons (optional) - -## Complete Example - -Here's a complete example of how to implement feature cards: - -1. Create or modify a JSON file in the data directory (e.g., `data/my-features.json`): - -```json -{ - "components": [ - { - "title": "Security", - "icon": "🔒", - "description": "Enterprise-grade security with robust authentication options." - }, - { - "title": "Analytics", - "icon": "📊", - "description": "Real-time insights into API usage and performance." - }, - { - "title": "Automation", - "icon": "⚙️", - "description": "Automate workflows and reduce manual intervention." - }, - { - "title": "Scalability", - "icon": "🚀", - "description": "Scale seamlessly to handle growth and demand spikes." - } - ] -} -``` - -2. Reference this data in the shortcode template (you'll need to modify the shortcode to use your custom data file). - -3. Use the shortcode in your markdown file with the custom data file: - -```md -{{}} -``` - -## Using Multiple Feature Card Sets - -You can use multiple different sets of feature cards in your documentation by: - -1. Creating additional JSON files in the data directory with different names -2. Specifying the appropriate data file when using the shortcode - -This approach allows you to have multiple independent sets of feature cards throughout your documentation. - -## Live Example - -The following example uses a custom data file called `ui-example-features.json`: - -```md -{{}} -``` - -Which renders as: - -{{< feature-cards dataFile="ui-example-features" >}} diff --git a/tyk-docs/content/ui-examples/test-pill-label-security.md b/tyk-docs/content/ui-examples/test-pill-label-security.md deleted file mode 100644 index be27edd0ca..0000000000 --- a/tyk-docs/content/ui-examples/test-pill-label-security.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "UI Examples: Pill Label Security Test" -date: 2024-04-23 -draft: true ---- - -## Security Test Cases for Pill Label Shortcode - -### Normal Usage -{{< pill-label text="NORMAL" >}} - -### HTML Injection Attempt -{{< pill-label text="" >}} - -### Invalid Class - Generates "Warning: Unsupported class" Message -{{< pill-label text="INVALID CLASS" class="not-allowed-class" >}} - -### Malicious Style Attempt - Generates "Warning: Potentially unsafe style attribute" Message -{{< pill-label text="BAD STYLE" style="javascript:alert('XSS');" >}} - -### Additional Unsafe Style Test - Generates "Warning: Potentially unsafe style attribute" Message -{{< pill-label text="SCRIPT IN STYLE" style="background-image: url('javascript:alert(1)');" >}} - -### Expression Style Test - Generates "Warning: Potentially unsafe style attribute" Message -{{< pill-label text="EXPRESSION" style="background: expression(alert('XSS'));" >}} - -### Safe Complex Style Attempt -{{< pill-label text="COMPLEX" style="color: red; background-color: yellow;" >}} - -## Warning Messages Generated During Build - -The Hugo build log should show these warnings for the malicious test cases: - -1. For invalid class: - ``` - Warning: Unsupported class 'not-allowed-class' used in pill-label shortcode. Using default class instead. - ``` - -2. For unsafe style attributes: - ``` - Warning: Potentially unsafe style attribute in pill-label shortcode was sanitized - ``` - -## IMPORTANT - -This page is set to `draft: true` to prevent it from being built in production, -avoiding warning messages in deployment logs. To test the security features: - -1. Run Hugo locally with the draft flag: `hugo serve -D` -2. Observe the warning messages in the terminal -3. Verify the rendered output in the browser diff --git a/tyk-docs/content/ui-examples/test-pill-label.md b/tyk-docs/content/ui-examples/test-pill-label.md deleted file mode 100644 index 3017ebe131..0000000000 --- a/tyk-docs/content/ui-examples/test-pill-label.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -title: "UI Examples: Pill label shortcode" -date: 2024-04-23 -draft: false ---- - -This page demonstrates all available styles and usage examples of the pill-label shortcode. - -**Feel free to contribute by adding more classes or adjusting the colors via PR.** - -Click on any example to see details about its usage and styling. - - ---- - -## Default style - Enterprise edition {#enterprise-edition} - -### Enterprise security features {{< pill-label text="EE" >}} - -
-Click to view usage and styling - -Type: Default Style - -Usage: Used for Enterprise Edition features - -Class name: `pill-outline-brandpurple-light` (default) - -This creates a pill with: -- Transparent background -- Dark purple (#8438fa) border -- Dark purple (#8438fa) text - -Example appearance: `[ EE ]` (outline style with purple text) - -Code example: -``` -### Enterprise security features {{}} -``` -
- ---- - -## Dark purple style - Cloud features {#cloud-features} - -### Governance {{< pill-label text="CLOUD" class="pill-brandpurple-dark" >}} - -
-Click to view usage and styling - -Type: Dark Purple Style - -Usage: Used for Cloud Features - -Class name: `pill-brandpurple-dark` - -This creates a pill with: -- Dark purple (#8438fa) background -- White text - -Example appearance: `[CLOUD]` (solid purple background with white text) - -Code example: -``` -### Cloud-only feature {{}} -``` -
- ---- - -## Yellow style - Lab releases {#lab-releases} - -### AI future feature {{< pill-label text="LAB RELEASE" class="pill-yellow" >}} - -
-Click to view usage and styling - -Type: Yellow Style - -Usage: Used for Lab Releases - -Class name: `pill-yellow` - -This creates a pill with: -- Yellow (#d6b218) background -- Black text - -Example appearance: `[LAB RELEASE]` (solid yellow background with black text) - -Code example: -``` -### Lab feature {{}} -``` -
- ---- - -## Red style - Deprecated features {#deprecated-features} - -### Tyk classic API definition {{< pill-label text="DEPRECATED" class="pill-red" >}} - -
-Click to view usage and styling - -Type: Red Style - -Usage: Used for Deprecated Features - -Class name: `pill-red` - -This creates a pill with: -- Red (#ff6c7d) background -- White text - -Example appearance: `[DEPRECATED]` (solid red background with white text) - -Code example: -``` -### Tyk classic API definition {{}} -``` -
- ---- - -## Light purple style - Tutorials {#tutorials} - -### Tyk streams getting started {{< pill-label text="TUTORIAL" class="pill-default" >}} - -
-Click to view usage and styling - -Type: Light Purple Style - -Usage: Used for Tutorials - -Class name: `pill-default` - -This creates a pill with: -- Light purple (#ededf9) background -- Medium purple (#505071) text - -Example appearance: `[TUTORIAL]` (light purple background with dark purple text) - -Code example: -``` -### Tyk streams getting started {{}} -``` -
- ---- - -## Green style - New features {#new-features} - -### New feature {{< pill-label text="NEW" class="pill-brandgreen" >}} - -
-Click to view usage and styling - -Type: Green Style - -Usage: Used for New Features - -Class name: `pill-brandgreen` - -This creates a pill with: -- Green (#00cdb0) background -- Black text - -Example appearance: `[NEW]` (solid green background with black text) - -Code example: -``` -### New feature {{}} -``` -
- ---- - -## Custom styling {#custom-styling} - -### Custom label {{< pill-label text="CUSTOM" style="background-color: #f0f0f0; color: #333; border: 1px solid #ccc;" >}} - -
-Click to view usage and styling - -Type: Custom Styling - -Usage: Used for special cases requiring custom styling - -Uses inline `style` attribute instead of class - -This creates a pill with custom inline styling - in this case: -- Light gray background -- Dark gray text -- Light gray border - -Example appearance: `[CUSTOM]` (custom styling as specified) - -Code example: -``` -### Custom label {{}} -``` -
- ---- - -## Reference table {#reference-table} - -| Class Name | Best For | Background | Text Color | Border | -|------------|----------|------------|------------|--------| -| pill-outline-brandpurple-light (default) | Enterprise Edition | Transparent | Dark Purple | Dark Purple | -| pill-brandpurple-dark | Cloud Features | Dark Purple | White | None | -| pill-yellow | Lab Releases | Yellow | Black | None | -| pill-red | Deprecated Features | Red | White | None | -| pill-brandgreen | New Features | Green | Black | None | -| pill-default | Tutorials | Light Purple | Medium Purple | None | diff --git a/tyk-docs/content/ui-examples/youtube-video-embed.md b/tyk-docs/content/ui-examples/youtube-video-embed.md deleted file mode 100644 index 721786050d..0000000000 --- a/tyk-docs/content/ui-examples/youtube-video-embed.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -date: 2025-04-28 -title: YouTube Video Embed -tags: ["UI Examples", "Shortcodes", "Video Embed"] -description: "Documentation for the youtube-seo shortcode in Tyk. Learn how to embed YouTube videos in your documentation with proper styling and responsive behavior." ---- - -The `youtube-seo` shortcode allows you to easily embed YouTube videos in your documentation with proper styling and responsive behavior. - -## When to Use - -Use the `youtube-seo` shortcode whenever you need to embed a YouTube video in your documentation, such as: - -- Product demonstrations -- Tutorial walkthroughs -- Conference presentations -- Webinar recordings -- Feature explanations - -The shortcode ensures consistent styling and proper SEO attributes for all embedded videos across your documentation. - -## Basic Usage - -To embed a YouTube video, simply use the shortcode with the video ID: - -```md -{{}} -``` - -Replace `VIDEO_ID` with the actual YouTube video ID (the part after `v=` in a YouTube URL) and `Video Title` with a descriptive title for the video. - -## Example - -```md -{{< youtube-seo id="J2BY7NYRk7U" title="Tyk API Gateway Overview">}} -``` - -## Parameters - -The shortcode supports several parameters: - -| Parameter | Required | Default | Description | -|-----------|----------|---------|-------------| -| id | Yes | - | The YouTube video ID | -| title | Yes | - | The title of the video (for SEO and accessibility) | -| width | No | 640 | The width of the video in pixels | -| height | No | 360 | The height of the video in pixels | -| allow | No | accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share | Permissions for the embedded iframe | -| frameborder | No | 0 | Border around the iframe | - -## Responsive Behavior - -The embedded video will: -- Be centered on the page -- Maintain its aspect ratio on all screen sizes -- Have appropriate margin spacing above and below -- Appear at a comfortable size (640x360 by default) - -## Advanced Usage - -If you need to customize the video dimensions: - -```md -{{< youtube-seo id="VIDEO_ID" title="Video Title" width="800" height="450" >}} -``` - -If you need to restrict certain iframe permissions: - -```md -{{< youtube-seo id="VIDEO_ID" title="Video Title" allow="accelerometer; encrypted-media" >}} -``` diff --git a/tyk-docs/data/menu.yaml b/tyk-docs/data/menu.yaml index 38af5bf134..641d1d57f9 100644 --- a/tyk-docs/data/menu.yaml +++ b/tyk-docs/data/menu.yaml @@ -859,22 +859,18 @@ menu: path: /developer-support/contributing category: Page show: True - - title: "Inclusive Naming" - path: /developer-support/documentation-projects/inclusive-naming - category: Page - show: True - - title: "UI Example: Pill Label Shortcode" - path: /ui-examples/test-pill-label + - title: "Content Guide" + path: /developer-support/contribution-guides category: Page show: true - - title: "UI Example: Feature Cards shortcode" - path: /ui-examples/feature-cards + - title: "Release Tyk Docs" + path: /developer-support/release-guide category: Page show: true - - title: "UI Example: YouTube Video Embed shortcode" - path: /ui-examples/youtube-video-embed + - title: "Inclusive Naming" + path: /developer-support/documentation-projects/inclusive-naming category: Page - show: true + show: True - title: "Developer Portal" category: Tab show: True