Best Practices for DevDocs

Deployment

• Deployment:

  • If first time deploying, select Force deploy all files.
  • If not, optionally include base SHA to use as a baseline - this will only deploy diffs which speeds up deployment.
  • More information: Deployment Guide

File and Directory Naming

• Use kebab-case names for files and directories:

  • Replace underscore (_) and period (.) with dash (-)

  • Remove special characters

  • Use lowercase letters for file names

  • Find and replace usages of that file in links

  • Why:

    • File paths with unsupported characters will fail to deploy to EDS.
    • Filenames are stricter in that underscores, periods, and uppercase letters are not allowed. Folder names are more lenient in that it allows underscores and uppercase letters, but not periods. For consistency and ease of remembering, it's best to use kebab-case all around.

• Place assets in src/pages (and not static folder):

  • Remove images or pdf content from static folder and put in src/pages folder
  • Redocly spec files: YAML can be in src/pages or static/; JSON must be in static/ only (JSON under src/pages fails deployment)

• Image file size limits:

  • SVG: keep under 40 KB.
  • PNG / JPG / GIF / WebP: keep under 20 MB.
  • See Image Block for full reference.

• Assets are reading from the branch it was deployed from

• Directly importing content from another repo doesn't work:

  • Because the file is unable to fetch data from the external repo.

Paths and Links

• Paths:

  • Use absolute paths when linking to other repos

  • Use absolute paths when linking to DevBiz

  • Use relative paths when linking within repo

  • Relative paths should be relative to path prefix

  • Relative links should include file name and extension (ex: index.md or other .md file)

    • except for anchor links that are in the current page (e.g. [description](#anchor))
    • note: anchor links don't work in local development - deploy to stage to test

  • Reference-style links for .md files:

    • You can list targets once at the bottom of the file and reference them by label in the body. This keeps long paths out of inline text.
    • Example:

To configure credentials for your integration, see [Authentication][2].

[//]: # (Links)
[1]: /docs/overview/index.md
[2]: /reference/authentication/index.md
[3]: /guides/release-notes/index.md

• To open link as external, use the query string ?aio_external in your URL:

  • Example: https://github.com/AdobeDocs/adp-devsite-github-actions-test/blob/main/src/pages/test/test-hr-0.md?plain=1#L13
  • This will have to open the external link manually.

• Config paths:

  • Use absolute prod path for home

    • e.g. [Home](https://developer.adobe.com/your-product/)

  • Relative paths should be relative to path prefix and not start with "/"

    • e.g. [Getting Started](guides/getting-started/index.md)
    • In HTML, paths that start with '/' are treated as relative to domain. However, DevDocs doesn't handle this yet.

  • Landing page (the page of the path-prefix) will not have side nav.

  • On any parent section page (like /guides/, /community/, etc.), the sidebar navigation automatically displays all the child pages within that section. For example, in the config.md, if there is any subpages (eg. /guides/code-contribution) which is within the same parent section, the sidenav will show up. This contextual sidebar appears for any page that has sub-pages, helping users easily navigate through related content without having to go back to higher-level pages.

    • Example: https://developer-stage.adobe.com/dev-docs-reference/blocks/

• Remove unnecessary trailing slashes from paths:

  • In Gatsby, invalid URLs that have unnecessary trailing slashes will work. However, in EDS they won't work
  • redirects.json will redirect Gatsby bookmarks (from invalid form to correct form). It's best to do this for a limited period of time, around 4-6 weeks.

• Links to other file types than .md and .json can use relative paths:

  • [ZIP](./assets/process.zip) <br/> [PDF for download](./assets/example.pdf) <br/>
  • In blocks, like Columns or Superhero, images and videos can also be in a relative path:

<Superhero slots="fullWidthBackground, video, heading, text, buttons" variant="halfWidth" textColor="white" overGradient />

![Gradient background](../../../assets/vertical-gradient.png)

[video_url](../../../assets/example-video.mp4)

# Page Heading

This is a sample description text for the superhero block.

* [Get Started](https://example.com/getting-started)
* [View Examples](https://example.com/examples)

• GitHub URLs for files that end in .md:

  • Use %2E in place of the period before md in the path so the URL resolves
  • Example: [README on GitHub](https://github.com/AdobeDocs/dev-docs-reference/blob/main/README%2Emd) — use %2E instead of . before md in the path segment (not ...README.md). We have a ticket logged to fix this so you don't need to use this workaround

• Fix dead links:

  • $npm run lint --dead-links-only: lists dead links. Run to prevent 404s. Check your package.json file for more linting scripts
  • More information: Linting Guide

Markdown Syntax Rules

• Links should use square brackets '[ ]' and not angle brackets '< >'

• Quotes should match

• Table number of columns should be the same on all rows:

  • Table won't render otherwise

• Use languages properly in the code block

• Don't nest blocks:

  • Don't nest a block within another block. For example, a code block cannot be within a table block.
  • Direct nesting of blocks in the source document is not a supported or recommended practice in AEM Edge Delivery Services

• HTML tags nor custom CSS are supported:

  • Avoid <br /> tag - Change any html characters with an escape character before:
    • Example: \<br /\> will work. or \{ \} or \<li\>
  • Escape any html tags within a table:
    • Example: \<li /\> within a table will render

• ---, * * *, nor <hr> are supported as a horizontal ruler. Replace with <HorizontalLine />

Config.md

• Config.md:

  • In Gatsby, Home is optional and overwrites Products
  • In EDS, Products is always displayed and Home must be the first path under Pages

Block Replacements

• New Block Names and Replacements:

  • Replace Hero default variant with Superhero default variant

  • Replace Hero halfwidth variant with Superhero halfWidth variant

  • Replace Hero fullwidth variant with Superhero centered variant

  • Replace Teaser with Announcement

  • Replace TextBlock with Cards or Columns

  • Replace AnnouncementBlock with Announcement

  • Replace SummaryBlock with Announcement

  • Replace MiniResourceCard with Cards

  • In InlineAlert block replace header slot with heading slot

  • Remove extra Accordion tags and only use: AccordionItem and rearrange so header is not in the tag

  • Replace ListBlock with List

  • Replace TabsBlock with Tab

  • Replace Media with Embed. Embed urls shouldn't be wrapped in angle brackets < >:

    • example: <Embed slots="video"/> not -> <Media slots="video"/>

    • Why:

      • Media and Embed were dupes. Only Embed exists now
      • Embed syntax doesn't call for angle brackets around the url

  • Replace openAPISpec with RedoclyAPIBlock:

    • YAML files: Can be under /src/pages (relative path) or in static/.
    • JSON files: Must be in static/ only — JSON under /src/pages will fail deployment.
    • static/ folder (at repo root): Use src="/{pathPrefix}/{pathToFileRelativeToStaticFolder}" — include pathPrefix, exclude the static segment.
    • Example (relative path): From api/reference/index.md referencing assets/openapi.yaml → <RedoclyAPIBlock src="../../assets/openapi.yaml" />
    • Example (static): For static/petstore.json with pathPrefix adobe-assurance-public-apis → src="/adobe-assurance-public-apis/petstore.json"

  • Replace Details HTML element with Details EDS block:

    • replace:

    <details>
      <summary>Text Description of Details</summary>
    - Workflow A:
      1. Step one
      2. Step two
      3. Step three
    </details>
    

    • with:

    <Details slots="heading , list" repeat="1" summary = "Text Description of Detail Block" subText="Diagram listing common use cases:"/>
    
    - Developer Distribution (Start with the listing metadata):
      1. Step one
      2. Step two
      3. Step three
    

    • EDS does not support Details HTML element. Use the Details EDS block instead.

• Fragments:

  • Use fragment
  • Example
  • Imports are now fragments. The connector will ensure imports are now fragments.

• SiteWidebanner:

  • Example: Add a file named site-wide-banner.json in the path:

    • /src/pages/site-wide-banner.json
    • Publish the page or deploy the file in the EDS branch, and it will be reflected automatically.
    • Example: https://github.com/AdobeDocs/adp-devsite-github-actions-test/blob/main/src/pages/sitewidebanner.json

  • This new announcement banner component visually will be more similar to Spectrum's alert banner. The alert banner is typically used for high-signal messages – they're meant to prompt the user to take action. The announcement banner is the dev site's version of the alert banner.