/video-streaming-developer-docs

Primary LanguageJavaScriptApache License 2.0Apache-2.0

Developer Tools

A documentation site for IBM Video Streaming APIs, SDKs and use cases - URL

About

With this repository Video Streaming developers can easily update their API and SDK documentations. The site content is in mdx format. MDX is like an extension of markdown documents. MDX is an authorable format that lets you seamlessly write JSX in your Markdown documents. You can import components, such as interactive charts or alerts, and embed them within your content. This makes writing long-form content with components a blast 🚀. MDX seeks to make writing with Markdown and JSX simpler while being more expressive.

How to contribute

To collaborate with this repository in GitHub you need to follow these steps:

  • Fork the repository into your own GitHub
  • Clone the repository to your local machine
  • Create a new branch for your changes
  • Make some changes and commit them with useful messages (Conventional Commit messages preferred)
  • Push the changes to your repository
  • Create a Pull Request from your repository back to the original one

Then the codeowners will review your Pull Request and if the PR is accepted and merged into master a Github Action will build and push the site to the gh-pages branch and the deployment is done.

How To

The site content and page structure can be found here: src/pages/

For example, you want to update the Channel API/Security/Embed Restriction page. Just navigate to src/pages/channel-api-security/ folder and update the embed-restriction.mdx file.

You can use Github UI to edit this file or you can checkout the repo and edit locally. For local development you can find instructions below.

Check out this article template file for available mdx components:

Local development

  1. Prerequisite:

    • Install NodeJS - brew install node

  2. Check out the repo

  3. CD into the repo dir

  4. Install the dependencies - npm install

  5. Run the site locally - npm run dev

Creating a new page

in order to create a new page, you have to

  1. extend the nav items file: src/data/nav-items.yaml

    Each api url must starts with the api name. api-basics, channel-api, viewer-authentication, player-api, analytics-api

  2. pages are in markdown format. Create the new mdx file in the src/pages/ directory, or edit an existing mdx file. Pages can be in the root in the pages directory. For example /player-api-usage, or it can be in a separate directory, /player-api-examples/basic-embed. Use directory is page if grouped in a main menu, use file if it stands alone. Examples of page contents can be found here:

Deployment

The project uses this Github Action to build and publish the site: Gatsby Publish

Tips

👷‍♂️ WIP

To mark your PR as work in progress (eg.: you wrote documentation to a feature which is not released yet) write WIP inside the PR's title. In this case merge is prevented by the WIP check. If the PR is ready to be merged (eg.: the documented feature is released) you could remove WIP from the title.

To add MDX support for your editor: