adobe / aio-theme Goto Github PK
View Code? Open in Web Editor NEWThe Adobe I/O theme for building markdown powered sites
License: Apache License 2.0
The Adobe I/O theme for building markdown powered sites
License: Apache License 2.0
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.
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>
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:
Adopting changes from #1383 (not sure what other changes/testing would be required).
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.
https://github.com/AdobeDocs/aep-mobile-sdkdocs
Adobe/Experience Platform Mobile SDK
The Hero component displays a scroll bar at certain page widths/zoom levels.
The Hero block should display a fixed image or solid color and not scroll at any width.
At some unknown medium width, the hero image has an extraneous scrollbar. At a very narrow or wide width this scrollbar is not present.
Maybe something in the CSS?
Minor aesthetic issue.
https://developer.adobe.com/commerce/webapi/
https://developer.adobe.com/commerce/webapi/
Commerce Documentation, but the bug affects all developer.adobe pages that use the hero block from what I've seen.
Ideally we should define default assets for BUs to always have the latest illustrations if they don't want to own it.
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.
The items in the dropdown list should be updated.
The initial list is used.
I'll submit a PR for how I've resolved this locally.
The specific context where I ran into this issue is that I'm building a dropdown list based on the /organizations/
IMS endpoint.
(this is still rough and has other issues but I wanted to get this issue filed before I forgot)
I'm seeing this locally running gatbsy develop.
Adobe/Cloud Manager
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
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?
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.
Photoshop
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:
Creative Cloud Developer Experience Team
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
TypeError: undefined is not an object (evaluating 'selectedTab.current')
positionIndicator
node_modules/@adobe/gatsby-theme-parliament/src/components/Tabs/index.js:19
16 | import { css } from '@emotion/core';
17 |
18 | const positionIndicator = (indicator, selectedTab) => {
> 19 | indicator.current.style.transform = `translate(${selectedTab.current.offsetLeft}px, 0px)`;
20 | indicator.current.style.width = `${selectedTab.current.offsetWidth}px`;
21 | };
22 |
View compiled
positionSelectedTabIndicator
node_modules/@adobe/gatsby-theme-parliament/src/components/GlobalHeader/index.js:62
59 | const selectedTabIndex = getSelectedTabIndex();
60 | const selectedTab = tabs.filter((tab) => tab.current)[selectedTabIndex];
61 |
> 62 | positionIndicator(selectedTabIndicator, selectedTab);
63 | };
64 |
65 | useEffect(() => {
View compiled
(anonymous function)
node_modules/@adobe/gatsby-theme-parliament/src/components/GlobalHeader/index.js:67
64 |
65 | useEffect(() => {
66 | animateIndicator(selectedTabIndicator, isAnimated);
> 67 | positionSelectedTabIndicator();
68 | }, [location.pathname]);
69 |
70 | useEffect(() => {
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.
Includes :
Update README with CLI commands (build, dev, clean, watch etc.)
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.
File: https://github.com/adobe/gatsby-theme-parliament/blob/main/README.md
Explain env vars:
GATSBY_LAUNCH_SRC=
GATSBY_LAUNCH_SRC_INCLUDE_IN_DEVELOPMENT=
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
Shouldn't be duplicates
There were duplicates
Use a Set to do de-duplication.
Explain whatβs allowed and how to structure files underneath to show the SideNav.
A 0
can be seen after the API name here:
Note that:
versions
property with an empty array or not."@adobe/gatsby-theme-parliament": "^2.1.3"
from v2.0.0The 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>
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.
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 ?
I'm trying to build a website for my company, using the gatsby theme based on Adobe Spectrum.
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
EMEXAL
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.
Adobe/STLab
e.g what's going on here https://github.com/AdobeDocs/gatsby-theme-parliament-product/blob/main/gatsby-config.js#L22
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 ?
I'm trying to build a website for my company, using the gatsby theme based on Adobe Spectrum.
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
EMEXAL
Hi Adobe I/O team, it would be awesome if code syntax highlighting/styling was available for more languages, for example:
With different highlighting for:
For example, in Android Studio the following code styling helps make it more visually understandable:
Gitbook example:
Potentially using a library with support for a ton of languages like: https://github.com/highlightjs/highlight.js
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/
Adobe/Experience Platform Mobile SDK
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 ..
The h1 style on redoc-generated pages (using OpenAPIBlock) use the font-family of 'Montserrat, sans-serif'
.
These headings should use Adobe clean
Wrong font used.
Set the family for the headings.
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>
TBody
should properly display provided children or be empty when none provided.
Component errors with:
Uncaught (in promise) TypeError: Cannot set properties of undefined (setting 'tableWidth')
Breaking change after aio-theme upgrade inside https://github.com/AdobeDocs/cloudmanager-api-docs.
Production
AEM Cloud Manager
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/>
.
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:
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.
My guess is that we need to account for the height taken up by the top-nav.
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.
The code should be displayed :)
Empty block.
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.
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.
<CodeBlock languages="JSON"
heading={
<Heading3>Response</Heading3>
}
code={
<Code className="language-json">{JSON.stringify({ foo: 'bar' })}</Code>
} />
Produces...
This was seen locally.
Adobe/Cloud Manager
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
Switch to publishing this package via github actions
Automated publishing to npm
Manual publishing to npm
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
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.
Adobe
n/a
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/
I suspect a bug in the Prism Syntax Highlighter.
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
Developer documentation
Thanks!
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)?
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.
Creative Cloud Developer Ecosystem - Developer Experience Team ππ»ββοΈ
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!
Discovering Adobe are using my Open-source work has absolutely made my day! Thanks team!!!
Is it possible to include markdown files as fragments within another markdown file in the same repo?
Example:
# Section 2
Here's some content that will be shown within another markdown file.
This is pseudocode/markdown:
import section2 from ./md1.md
# Section 1
Here's some content within this file.
@section2
Add support for reference-style links in MDX for static builds.
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.
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
.
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.
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.
For Magento Cloud specific deployment instructions, see the [Magento Cloud deployment][] tutorial.
[magento cloud deployment]: /tutorials/production-deployment/magento-cloud/
Magento/devdocs
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.
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?
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
I would like to use the Enhanced Markdown in the theme.
I have installed the @adobe/[email protected] and added it to the gatsby-config.js plugin
plugins: [ '@adobe/gatsby-theme-aio']
e.g how to use JSDocParameters
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 ?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. πππ
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google β€οΈ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.