e.g what's going on here https://github.com/AdobeDocs/gatsby-theme-parliament-product/blob/main/gatsby-config.js#L22

❔ Question

After running npm run dev, I have always the error

error There was an error in your GraphQL query:
Cannot query field "path" on type "GithubContributors".

Can you please suggest what is wrong, and what am I missing ?

🔦 Context

I'm trying to build a website for my company, using the gatsby theme based on Adobe Spectrum.

🌍 Your Environment

Windows x64, NodeJS v14.15.4, npm 6.14.10

.env file content

REPO_GITHUB_TOKEN=xxxxxxxxxxx
REPO_OWNER=AdobeDocs
REPO_NAME=dev-site-documentation-template
REPO_BRANCH=main

🧢 Your Company/Team

EMEXAL

File: https://github.com/adobe/gatsby-theme-parliament/blob/main/README.md

Our theory:

If a page falls under the pages property path in gatsby-config, that page is set as active in top nav. Otherwise, it now defaults to the primary tab.

Current

Currently, if I click the "Go live" link (/#go-live) seen in the top nav in the screenshot below, the scroll jumps past the "Go live" heading which contains the anchor id:

Desired

Preferably, we'd be able to see the heading after the scroll:

Note that the above is simply an example (I'm not totally sold we'll do this type of linking from top nav on the docs top page).

However, this phenomenon is present in more legitimate use cases for named anchors as well, like the autogenerated right-hand table-of-contents in narrative content.

Possible source of issue

My guess is that we need to account for the height taken up by the top-nav.

Includes :

• AnouncementBlock
• Header variants
• ProductCard
• ResourceCard
• SummaryBlock
• TextBlock
• TitleBlock

🙋 Feature Request

Switch to publishing this package via github actions

🤔 Expected Behavior

Automated publishing to npm

😯 Current Behavior

Manual publishing to npm

💁 Possible Solution

Many other teams have moved to github action based publishing. We have an example workflow in our starter repo:

https://github.com/adobe/starter-repo/blob/master/.github/workflow/npm-publish.yml

but others have written their own workflows for instance, semantic release:

https://github.com/adobe/helix-cli/blob/main/.github/workflows/semantic-release.yaml

🔦 Context

ASSET is working with us to secure our npm org and we will be removing individual accounts from the org to reduce the attack surface.

💻 Examples

🧢 Your Company/Team

Adobe

🎁 Tracking Ticket (optional)

n/a

File: https://github.com/adobe/gatsby-theme-parliament/blob/main/README.md

Explain env vars:

GITHUB_TOKEN=
GITHUB_REPO_OWNER=adobe
GITHUB_REPO_NAME=gatsby-theme-parliament
GITHUB_REPO_BRANCH=main
ROOT=example

🙋 Documentation Request

The instructions to force a full rebuild in the readme are incorrect:

yarn clean && yarn cache clean && rm node_modules && rm yarn.lock

should be:

yarn clean && yarn cache clean && rm -r node_modules && rm yarn.lock

Otherwise, the rm node_module will fail because node_modules is a directory and the yarn.lock file will not be removed.

🧢 Your Company/Team

Adobe/STLab

🐛 Bug Report

If a contributor's GitHub username is both listed in contributors in the front-matter and the list of usernames retrieved from github, there will be duplicate icons

🤔 Expected Behavior

Shouldn't be duplicates

😯 Current Behavior

There were duplicates

💁 Possible Solution

Use a Set to do de-duplication.

🔦 Context

💻 Code Sample

🌍 Your Environment

🧢 Your Company/Team

🕷 Tracking Issue (optional)

Explain what’s allowed and how to structure files underneath to show the SideNav.

The issue

A 0 can be seen after the API name here:

Note that:

• This issue is present regardless of whether the config contains a versions property with an empty array or not.
• I hadn't noticed this issue previously, and I just updated to "@adobe/gatsby-theme-parliament": "^2.1.3" from v2.0.0

The code

The gatsby config is here:
https://github.com/AdobeDocs/cc-libraries-api/blob/main/gatsby-config.js#L19-L20

This is the resulting HTML:

<div
  class="spectrum-Tabs spectrum-Tabs--horizontal spectrum-Tabs--quiet"
  role="tablist"
>
  <a
    aria-current="page"
    role="tab"
    aria-selected="true"
    class="spectrum-Tabs-item is-selected"
    href="/"
    ><span class="spectrum-Tabs-itemLabel">CC Libraries API</span></a
  >0<a
    role="tab"
    aria-selected="false"
    class="spectrum-Tabs-item"
    href="/integrate/"
    ><span class="spectrum-Tabs-itemLabel">Integrate</span></a
  ><a
    role="tab"
    aria-selected="false"
    class="spectrum-Tabs-item"
    href="/go-live/"
    ><span class="spectrum-Tabs-itemLabel">Go live</span></a
  ><a role="tab" aria-selected="false" class="spectrum-Tabs-item" href="/api/"
    ><span class="spectrum-Tabs-itemLabel">API Reference</span></a
  >
  <div
    class="spectrum-Tabs-selectionIndicator css-101vd50-TabsIndicator-GlobalHeader"
    style="transition: none; transform: translate(8px, 0px); width: 90px"
  ></div>
  <div
    style="
      margin-left: var(
        --spectrum-global-dimension-size-400,
        var(--spectrum-alias-size-400)
      );
    "
  ></div>
</div>

This might be a good place to collect markdown/markup FAQs to be documented in the readme.

To start, I've noticed that unclosed <br> tags will crash the parser. Self-closed tags work as expected: <br/>.

• Grid should be 9cols and 3col Resources (Overview / Guides / Support)
• GlobalHeader Adobe Icon is too big
• Align the Footer with the content
• OnThisPage should always be positioned to the right side of the page (also remove navigate to section dropdown)
• Switch Feedback Toast to Modal
• Fix Versions Popover opening behind Discover/Docs Popover

🙋 Feature Request

Add support for reference-style links in MDX for static builds.

🤔 Expected Behavior

The following markdown:

This is an [internal reference-style link][].

[internal reference-style link]: /path/to/page/

Should be rendered as a link with the pathPrefix prepended to the destination when creating the static builds for staging and production.

😯 Current Behavior

Staging and production builds do not prepend the link destination with the site's pathPrefix.

This can be seen when building content that uses reference-style links and publish to staging.
The link paths from this content will not have the prefix prepended to the href.

💁 Possible Solution

Add the remark-inline-links plugin to the MDX plugin's options.remarkPlugins array.

   {
        resolve: `gatsby-plugin-mdx`,
        options: {
          extensions: [`.mdx`, `.md`],
          defaultLayouts: {
            default: require.resolve(`./src/components/MDXFilter/index.js`)
          },
          rehypePlugins: [require(`rehype-slug`)],
          plugins: [`gatsby-remark-copy-linked-files`, `gatsby-remark-images-remote`],
          gatsbyRemarkPlugins: [
            {
              resolve: `gatsby-remark-copy-linked-files`,
              options: {
                ignoreFileExtensions: [`png`, `jpg`, `jpeg`, `bmp`, `tiff`, `md`, `mdx`]
              }
            },
            {
              resolve: `gatsby-remark-images-remote`,
              options: {
                maxWidth: LARGE_SCREEN_WIDTH,
                linkImagesToOriginal: false,
                withWebp: { quality: 80 },
                disableBgImage: true,
                backgroundColor: 'none'
              }
            }
          ],
+        remarkPlugins: [require('remark-inline-links')],
        }
      },

This transforms reference-style links in the underlying markdown into inline links, which produce the correct links in static builds.

🔦 Context

The markdown content I am migrating into this framework almost exclusively uses reference-style links, which is valid markdown syntax.
Using this format makes authoring, reading, and reviewing the raw markdown easier.

For local development builds, this is not a problem because pathPrefix is not used, but when uploading static builds to the staging server where the content does not sit at the root, this becomes an issue.

💻 Examples

For Magento Cloud specific deployment instructions, see the [Magento Cloud deployment][] tutorial.

[magento cloud deployment]: /tutorials/production-deployment/magento-cloud/

🧢 Your Company/Team

Magento/devdocs

🎁 Tracking Ticket (optional)

🙋 Documentation Request

In this ReadMe: https://github.com/adobe/gatsby-theme-aio/blob/main/README.md

I need more guidance for teams on ideal image sizes (or illustration sizes) for the different blocks.

It's my understanding that for a 2-column layout, like the Text Block, there's a 350 max height... is there an ideal width? This 350 px max should also be noted in the Text Block documentation section: https://github.com/adobe/gatsby-theme-aio#text-block

In the documentation there isn't a distinction between 2-column and 3-column layouts, both are "Text Blocks" but the image recommendations are very different for each. It's my understanding that 3-column layouts are intended for large icons or illustrations, but how large? Is there a minimum or maximum that may break the design?

It would be ideal to read about either minimum, maximum, (or both) image sizes, or at the very least, image ratios (for example, 3:4, or "square", etc. ) for all the types of blocks meant to include image assets:

• Hero Block
• Resources Block
• Discover Block
• Summary Block
• Text Block
• Product Card
• Resource Card

🧢 Your Company/Team

Creative Cloud Developer Experience Team

Minicard component has some css issues (errors and needs some features), adding text content as optional and also make the whole card as a link.

No semi-colon here:

Results in the height not being set properly.

Text content should be option-able. This check will fail and throw an error if no text content is present:
https://github.com/adobe/aio-theme/blob/c293c01ac7340e498dacb6cb0716f8406638fb83/packages/gatsby-theme-aio/src/components/MiniResourceCard/index.js#L103C9-L103C9

The https://github.com/AdobeDocs/express-for-developers/ has a use-case of using the Minicard component without text body:
https://github.com/AdobeDocs/express-for-developers/blob/main/src/pages/index.md?plain=1#L80

The whole card should act as a link. May need another variant to support this as only the image is clickable.

Currently it's limited to to 3 due to Spectrum's recommendation

The multi-level side navigation should only go 3 levels deep

This should be doubled at least or infinite ?

1. In Using the Adobe I/O CLI it talks about passing a template option to the aio cli to use a different template. We really don’t want customers using a different template for the website right?
2. The part about Adding a Path Prefix will become very important when a bunch of microsites are combined into the one uber site. Gatsby navigation won’t work correctly if the path prefix is not right.
3. For the Content Structure we only show folders with index.md in them. Since lots of teams will be porting markdown files from pre-existing doc repos they will have names like JWTCertificate.md so we should make it plain that they don’t need to rename every file to index.md and put in in a directory called jwt_certificate.
4. In Front Matter Support we mention adding a title to the page but we also have the title in gatsby-config.js. Do we need the title in both places? This will become important for the search functionality.
5. For Specifying external contributors what does the url point to? Is it just an image file? I guess I’m a little confused how this is supposed to work.
6. We may have to change the way OpenAPI spec are defined. If we end up doing a full site search then we’ll need to add the spec to the search index. I will propose we have a list of OpenAPI specs that should be added to the site which can be local to the project or remote via http. Then we can updated the Gatsby-node.js file to read the list and create all the pages.
7. I forgot to ask before but why do we need to add jsDoc: true to frontmatter?
8. Do we even want to mention Customizations? We don’t actually want people messing with the Code or Button components do we?

🐛 Bug Report

The Hero component displays a scroll bar at certain page widths/zoom levels.

🤔 Expected Behavior

The Hero block should display a fixed image or solid color and not scroll at any width.

😯 Current Behavior

At some unknown medium width, the hero image has an extraneous scrollbar. At a very narrow or wide width this scrollbar is not present.

💁 Possible Solution

Maybe something in the CSS?

🔦 Context

Minor aesthetic issue.

💻 Code Sample

https://developer.adobe.com/commerce/webapi/

🌍 Your Environment

https://developer.adobe.com/commerce/webapi/

🧢 Your Company/Team

Commerce Documentation, but the bug affects all developer.adobe pages that use the hero block from what I've seen.

🐛 Bug Report

php code blocks in the dev site do not appear to highlight any syntax.

Here is a page with several php code blocks: https://developer.adobe.com/commerce/webapi/get-started/gs-curl/

💁 Possible Solution

I suspect a bug in the Prism Syntax Highlighter.

💻 Code Sample

Here is a link to the github .md page for the file linked above: https://github.com/AdobeDocs/commerce-webapi/blob/main/src/pages/get-started/gs-curl.md?plain=1

🧢 Your Company/Team

Developer documentation

Thanks!

📝 Feedback

In this section: https://github.com/adobe/gatsby-theme-aio#using-the-adobe-io-cli

aio discover -i
Select the @adobe/aio-cli-plugin-doc plugin by pressing the Spacebar and finally press Enter to install it.

The aio-cli-plugin-doc is no longer an option. Does that mean I've already installed it globally, or that it's no longer available (is it deprecated)?

🔦 Context

I need to open 12 new repos here: https://github.com/AdobeDocs - one for each Creative Cloud product. I need to onboard new authors, and am hoping for more clarity in the Getting Started doc.

🧢 Your Company/Team

Creative Cloud Developer Ecosystem - Developer Experience Team 🙋🏻‍♀️

🐛 Bug Report

TBody component will throw a TypeError whenever the children provided to it represent a single item array.

E.g.:

<TBody>
  {singleItemArray.map(item => <Tr />)}
</TBody>

🤔 Expected Behavior

TBody should properly display provided children or be empty when none provided.

😯 Current Behavior

Component errors with:

Uncaught (in promise) TypeError: Cannot set properties of undefined (setting 'tableWidth')

💁 Possible Solution

#1517

🔦 Context

Breaking change after aio-theme upgrade inside https://github.com/AdobeDocs/cloudmanager-api-docs.

💻 Code Sample

https://github.com/AdobeDocs/cloudmanager-api-docs/blob/main/src/components/playground/link-table.js#L67

🌍 Your Environment

Production

🧢 Your Company/Team

AEM Cloud Manager

🕷 Tracking Issue (optional)

Can we add a watcher to restart/rebuild the server when the gatsby-config changes?

As-is currently (while running npm run dev), editing gatsby-config causes the script to reload (?) the site in place, but this rarely seems to be successful. The fix is usually to stop and restart the server manually.

❔ Question

After running npm run dev, I have always the error

error There was an error in your GraphQL query:
Cannot query field "path" on type "GithubContributors".

Can you please suggest what is wrong, and what am I missing ?

🔦 Context

I'm trying to build a website for my company, using the gatsby theme based on Adobe Spectrum.

🌍 Your Environment

Windows x64, NodeJS v14.15.4, npm 6.14.10

.env file content

REPO_GITHUB_TOKEN=xxxxxxxxxxx
REPO_OWNER=AdobeDocs
REPO_NAME=dev-site-documentation-template
REPO_BRANCH=main

🧢 Your Company/Team

EMEXAL

🙋 Feature Request

Hi Adobe I/O team, I wanted to request adoption of MDX v2 in order to enable interleaving of JSX and markdown, as solved in mdx-js/mdx#1039.

🤔 Expected Behavior

My understanding (and please let me know if I'm mistaken!) was that the <Variant /> tag needs to use the repeat=x system because in MDX v1 it's not possible to have constructs like this:

<Variant platform="android" api="extension-version">

#### Java

**Syntax**

\```java
public static String extensionVersion();
\```

</Variant>

😯 Current Behavior

And instead currently require this:

<Variant platform="android" api="extension-version" repeat="3"/>

#### Java

**Syntax**

\```java
public static String extensionVersion();
\```

Which can be quite cumbersome to keep track of and update, especially when making a lot of structural/content changes across a documentation repo.

Potentially related, I found this known limitation of MDX v1:

💁 Possible Solution

Adopting changes from #1383 (not sure what other changes/testing would be required).

🔦 Context

In the Adobe Experience Platform Mobile SDK docs using Adobe I/O, we use a lot of code tabs to show snippets and examples, and each of those tabs use <Variant> blocks to show the tab content: https://developer.adobe.com/client-sdks/documentation/consent-for-edge-network/api-reference/#registerextension

Making sweeping changes to the structure or content of these blocks can be hard because you have to keep track of and update all the repeat counts. Being able to mark the start and end of <Variant> ... </Variant> blocks using interleaved JSX would make it a lot easier to maintain the docs.

💻 Examples

https://github.com/AdobeDocs/aep-mobile-sdkdocs

🧢 Your Company/Team

Adobe/Experience Platform Mobile SDK

🎁 Tracking Ticket (optional)

🙋 Documentation Request

The inline alert image is broken in the repo readme. The link 404s: https://github.com/adobe/aio-theme/blob/main/docs/images/inline-alert-variants.png

🧢 Your Company/Team

🙋 Documentation Request

I would like to add following things in contributiong.md or create a new file for the same
1.Difference between GIT and GITHUB
2.How to clone,fork repository
3.How to create a branch and then use git push to push to repo
4.Create a PR
5.Squash commits in a single issue into one
6, Updating the forked and local repo as the updations are made in the upstream

🐛 Bug Report

Images referenced in markdown and imported via MDX from an external repository are ignored.

For example, the markdown file https://raw.githubusercontent.com/AdobeDocs/uxp/main/src/pages/uxp/reference-spectrum/User%20Interface/sp-button.md that references an image is imported as following

import Content from "uxp-documentation/src/pages/uxp/reference-spectrum/User Interface/sp-button";

<Content query="product=photoshop"/>

And because the image is not in the src/pages folder of the uxp-photoshop repositoroy but under node_modules, it's ignored ..

🐛 Bug Report

The h1 style on redoc-generated pages (using OpenAPIBlock) use the font-family of 'Montserrat, sans-serif'.

🤔 Expected Behavior

These headings should use Adobe clean

😯 Current Behavior

Wrong font used.

💁 Possible Solution

Set the family for the headings.

🔦 Context

💻 Code Sample

🌍 Your Environment

🧢 Your Company/Team

🕷 Tracking Issue (optional)

📝 Feedback

Hi, I'm Paul. I'm the chap that made MDX Embed. I spotted this morning that you're using it... I'm really excited by this and if there's anything i can help with please do let me know!

🔦 Context

Discovering Adobe are using my Open-source work has absolutely made my day! Thanks team!!!

❔ Question

Hello there,

Can I use this theme with an existing gatsby project? or do I have to use a template for the initial setup?

Thank you

🔦 Context

I would like to use the Enhanced Markdown in the theme.

💻 Code Sample

I have installed the @adobe/[email protected] and added it to the gatsby-config.js plugin
plugins: [ '@adobe/gatsby-theme-aio']


🌍 Your Environment

🧢 Your Company/Team

🐛 Bug Report

I'm trying to use the Picker component in a context where the items array is populated client-side. What I'm seeing is that when the items prop changes, it isn't actually reflected in the list of items in the dropdown.

🤔 Expected Behavior

The items in the dropdown list should be updated.

😯 Current Behavior

The initial list is used.

💁 Possible Solution

I'll submit a PR for how I've resolved this locally.

🔦 Context

The specific context where I ran into this issue is that I'm building a dropdown list based on the /organizations/ IMS endpoint.

💻 Code Sample

https://github.com/justinedelson/cloudmanager-api-docs/blob/c05843a339a0887af6ce1d146560baa21dcfa373/src/components/playground/org-id-selector.js#L58-L61

(this is still rough and has other issues but I wanted to get this issue filed before I forgot)

🌍 Your Environment

I'm seeing this locally running gatbsy develop.

🧢 Your Company/Team

Adobe/Cloud Manager

🕷 Tracking Issue (optional)

Before:

Now:

🐛 Bug Report

If a string is passed to the Code component which is not terminated in a newline, no code "content" is displayed. See screenshot below. Although it is copied to the clipboard if you click the copy button.

🤔 Expected Behavior

The code should be displayed :)

😯 Current Behavior

Empty block.

💁 Possible Solution

Instead of always removing the last item from the tokens array, the component should remove the last item if and only if the token is blank.

🔦 Context

Trying to use Code and CodeBlock in a JS component. My assumption is that these components were primarily intended for use in MDX which is possibly why this issue hasn't been encountered before.

It is, of course, possible to just add a newline to any text passed to the Code component. But that's frankly a bit error prone. And this issue took me a while to figure out (which may say more about me, but whatever...) so I'd like to help the next person trying to do this avoid troubleshooting time.

💻 Code Sample

 <CodeBlock languages="JSON"
        heading={
            <Heading3>Response</Heading3>
        }
        code={
             <Code className="language-json">{JSON.stringify({ foo: 'bar' })}</Code>
} />

Produces...

🌍 Your Environment

This was seen locally.

🧢 Your Company/Team

Adobe/Cloud Manager

🕷 Tracking Issue (optional)

Is it possible to include markdown files as fragments within another markdown file in the same repo?

Example:

File 1 (md1.md)

# Section 2
Here's some content that will be shown within another markdown file.

File 2 (md2.md)

This is pseudocode/markdown:

import section2 from ./md1.md

# Section 1
Here's some content within this file.

@section2

🙋 Feature Request

Hi Adobe I/O team, it would be awesome if code syntax highlighting/styling was available for more languages, for example:

• Java (doesn't seem to be available currently?)
• Kotlin
• Swift
• Bash
• etc.

With different highlighting for:

1. Access modifier & keywords (ex: public, private, static, final, function, if, else, etc.)
2. Data types (ex: void, String, Bool, Map<String, Object>)
3. Function/method names (ex: myFoo(), class.someBar())
4. Variables
5. Classes
6. Annotations (ex: @JvmStatic, @jvmoverloads, @available(macOS 10.15, *), etc.)

🤔 Expected Behavior

For example, in Android Studio the following code styling helps make it more visually understandable:

Gitbook example:

https://aep-sdks.gitbook.io/docs/foundation-extensions/consent-for-edge-network/api-reference#updateconsents

😯 Current Behavior

https://developer.adobe.com/client-sdks/documentation/consent-for-edge-network/api-reference/#updateconsents

💁 Possible Solution

Potentially using a library with support for a ton of languages like: https://github.com/highlightjs/highlight.js

🔦 Context

For the Adobe I/O docs for the Mobile SDK, code syntax and examples are a crucial part of the developer experience and code highlighting for all the languages we support would greatly improve readability:

https://developer.adobe.com/client-sdks/documentation/mobile-core/api-reference/

💻 Examples

🧢 Your Company/Team

Adobe/Experience Platform Mobile SDK

🎁 Tracking Ticket (optional)

Update README with CLI commands (build, dev, clean, watch etc.)

Before:

Now:

e.g how to use JSDocParameters

File: https://github.com/adobe/gatsby-theme-parliament/blob/main/README.md

Explain env vars:

GATSBY_LAUNCH_SRC=
GATSBY_LAUNCH_SRC_INCLUDE_IN_DEVELOPMENT=

For details on core issue, see gatsbyjs/gatsby#22135

It would be nice to bake a tool like this in to whatever npm script content authors are going to use.

Component: https://github.com/adobe/gatsby-theme-parliament/blob/main/packages/gatsby-theme-parliament/src/components/Feedback.js

For Adobe Launch, to query select the appropriate button elements, I could use the existing nested styles to select the buttons but it would be better to use a constant selector, so we should use a fixed classname for example. Are there any issues in adding this?

❔ Question

Gatsby was recently put into 'maintenance mode' by the new owners at Netlify, with all the features of Gatsby being rolled up into the Netlify stack. The team has all been fired back in August 2023, and there is nobody maintaining it, see links in this thread: https://fediverse.zachleat.com/@zachleat/110927844356705881

Gatsby is also pretty heavy when it comes to static site generation, unnecessarily complex, and slow to generate pages. Would the team consider a move to eleventy instead?

🔦 Context

Site generation is slow, and the produced output of Gatsby generated sites is also slow (being very JS heavy and 'React-first'). This impacts user experience for any sites we create for external customers, as well as impacts developer velocity when generation times are increasingly a bottleneck.

Additionally with Gatsby no longer having support, this will quickly become a security vulnerability for us as the packages it depends on will not be updated.

🧢 Your Company/Team

Photoshop

Ideally we should define default assets for BUs to always have the latest illustrations if they don't want to own it.