> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logictwelve.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> Use Stoplight Elements for Confluence day to day

Page viewers see either a three-panel API reference (endpoints, schemas, and a **Try It** console) from the **Stoplight Elements** macro, or a full embedded dev portal from the **Stoplight Elements Dev Portal** macro — rendered in place, with no Confluence-specific chrome around it.

If a macro is missing required configuration, viewers see a configuration warning instead. If the site doesn't have an active license, they see a license warning instead — see [Licensing](#licensing).

## Adding the macro to a page

<Steps>
  <Step title="Open the macro browser">
    While editing a page, type `/` or click the **+** in the editing toolbar.
  </Step>

  <Step title="Find and select the macro">
    Search for "Stoplight Elements" and select **Stoplight Elements** or **Stoplight Elements Dev Portal**:

    <Frame>
      <img src="https://mintcdn.com/logictwelve-a6acb4a5/ri-T8bkJTW8gw2zt/stoplight-confluence/images/macro-picker.png?fit=max&auto=format&n=ri-T8bkJTW8gw2zt&q=85&s=ed97d05d6d66e5df473e25a6852eec11" alt="Macro picker showing the Stoplight Elements macro" width="744" height="502" data-path="stoplight-confluence/images/macro-picker.png" />
    </Frame>
  </Step>

  <Step title="Set up the macro">
    Fill in the config form — see [Configuration](/stoplight-confluence/configuration) for every field.
  </Step>

  <Step title="Save">
    Click **Save** on the macro, then save the page to make the rendered documentation visible to viewers. Here's how the Elements macro looks once published:

    <Frame>
      <img src="https://mintcdn.com/logictwelve-a6acb4a5/ri-T8bkJTW8gw2zt/stoplight-confluence/images/macro-rendered.png?fit=max&auto=format&n=ri-T8bkJTW8gw2zt&q=85&s=eecce4bbfa67a761a005ae4d9deccc5f" alt="Rendered Stoplight Elements macro on a published Confluence page" width="2788" height="1650" data-path="stoplight-confluence/images/macro-rendered.png" />
    </Frame>
  </Step>
</Steps>

## Keeping it updated

How the macro stays current depends on what you pointed it at:

* **API Description URL** (Elements macro) or **Project ID** (Dev Portal macro) — fetched live every time someone views the page, so changes to the underlying spec or Stoplight project show up automatically. There's nothing to republish.
* **API Description Document** (pasted YAML/JSON, Elements macro only) — stored as a static snapshot in the macro's configuration. It only changes when you reopen the macro and paste in the updated content.

## Licensing

The app uses Confluence's built-in Marketplace licensing. If a site doesn't have an active license or trial, every instance of either macro shows a license warning instead of rendering.

## Tips

<AccordionGroup>
  <Accordion title="Spec isn't publicly reachable">
    Use **Document** instead of **URL** on the Elements macro and paste the OpenAPI YAML or JSON directly into the config.
  </Accordion>

  <Accordion title="Macro feels cramped">
    Confluence pages default to a fixed width. Use the page options menu to switch the page to **Go wide** or **Go full width** instead of changing the macro's own settings.
  </Accordion>

  <Accordion title="Read-only audience">
    Turn on **Hide Try It** in **Filter** to remove the interactive console and present a reference-only view.
  </Accordion>
</AccordionGroup>