Skip to content

feature(documentation): add ability to embed GitLab UI stories

Paul Gascou-Vaillancourt requested to merge poc-embedded-iframes into main

Note: This MR relies on an open GitLab UI MR: gitlab-org/gitlab-ui!2291 (merged). Until that MR is merged, this new feature can only be tested locally.

This adds the ability to embed GitLab UI stories in Pajamas website.

This is done by exposing a new stories frontmatter option as well as a Story: shortcode. The process for including stories has been documented in 98888e82.

This MR also migrates to this new approach for Alert and Banner docs pages.

👀 How does it look like?

  • When embedding stories in a docs page, they are rendered as cards containing a single story:
Before After
Screen_Shot_2021-11-25_at_12.40.29_PM Screen_Shot_2021-11-25_at_1.37.28_PM
  • When linking a GitLab UI docs page to a Pajamas one, it is rendered in the Implementation page:
Before After
Screen_Shot_2021-11-25_at_12.42.05_PM Screen_Shot_2021-11-25_at_12.41.51_PM
  • Since the stories are being included via iframes, there is a delay while the content is being loaded. Thanks to iframe-resizer, we can properly size iframes so that they expand to their content's height and don't need to be scrolled into.

stories

How to test this?

While this is under development, you need to test this against local instances of Pajamas and GitLab UI.

  1. Pull gitlab-org/gitlab-ui!2291 (merged) locally and run Storybook:
    yarn start
  2. Pull this branch locally.
  3. Make sure your dependencies are up-to-date:
    yarn
  4. Run the Pajamas app with a link to your local GitLab UI instance. For example, if Storybook is running at http://localhost:9001:
    GITLAB_UI_URL=http://localhost:9001 yarn start

Related to #1175 (closed).

Edited by Lukas 'ai-pi' Eipert

Merge request reports