## 1. Project Overview & Quickstart (elyra-ai/development-workflow) # development-workflow Open-source repository elyra-ai/development-workflow ### Repository Details - **Repository:** [elyra-ai/development-workflow](https://github.com/elyra-ai/development-workflow) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (elyra-ai/website) ## File: README.md This repository is currently in maintenance mode. Pull requests and changes are still being considered, but not actively monitored. --- ## File: src/pages/guides/navigation/sidebar.mdx --- title: Navigation tabs: ['Sidebar', 'Tabs'] --- One of the most important pieces of making a working site is to define your navigation items. This allows the theme to inform the SideNav component as well as the next/previous components at the bottom of each page. ## Yaml data Unfortunately, genenerating left nav contents purely from the pages directory has some fatal flaws. It makes it very difficult to establish the order of items or to hide items all together. In `src/data/nav-items.yaml`, you’ll list your nav items in order. ```yaml - title: Menu pages: - title: Page 1 path: /menu/Page-1 - title: Page 2 path: /menu/Page-2 - title: Single Page pages: - path: /single-page ``` Some important things to note here: - You only need to link to the first tab if using page tabs - The `title` refers to the menu and item text, it’s allowed to have spaces - The `path` refer to the relative path to the mdx file in your pages - You can make a `Page/index.mdx` file if you’d prefer to have assets in a folder. The path would still just look like `/Page` ## Adding a divider You can insert a divider below any top-level nav item by adding the `hasDivider: true` property to it's configuration under `src/data/nav-items.yaml`. **Note:** dividers can only be use with top-level nav items and are incompatible with the [header navigation style](/guides/configuration#navigation-style). When shadowed, the `ResourceLinks` component can optionally receive an `includeDividerSpace` prop. Set this to false if you want to remove the margin above and below the `ResourceLinks` divider. ```yaml - title: Menu pages: - title: Page 1 path: /menu/Page-1 - title: Page 2 path: /menu/Page-2 hasDivider: true - title: Single Page pages: - path: /single-page ``` In the example above, a divider will appear between **Menu** and **Single Page**. ## Customizing The nav item list can be customized using Gatsby theme [shadowing](/guides/shadowing). Simply provide your own implementation of `/src/util/NavItems.js` which can augment or replace the nav items read from `src/data/nav-items.yaml`. ```javascript // /src/util/NavItems.js import { useNavItems as themeUseNavItems } from 'gatsby-theme-carbon/src/util/NavItems'; // add nav items export function useNavItems() { const navItems = themeUseNavItems(); return navItems.concat({ title: 'Additional Nav Item', pages: [ { path: '/page1', title: 'New Page 1' }, { path: '/page2', title: 'New Page 2' }, ], }); } ``` --- ## File: src/pages/guides/navigation/tabs.mdx --- title: Navigation tabs: ['Sidebar', 'Tabs'] --- You have the option of adding tabs to your pages. This is only recommended if you have several pages that will use the same tabs. If you only have one page with a set of tabs, it might be better for discoverability to change the tabs to menu items. ## Tabs in YAML To create a tabbed page, you just need to point the theme to the path of your first tab. This is the structure of the YAML configuration for this page and it’s siblings. ```yaml - title: Guides pages: - title: Configuration path: /guides/configuration - title: Shadowing path: /guides/shadowing - title: Styling path: /guides/styling - title: Navigation path: /guides/navigation/sidebar ``` ## File structure Let’s check out the directory structure for this page. Notice how you’ll add another directory that corresponds with the one in the YAML file. . ├── pages │ └── guides │ ├── configuration.mdx │ ├── shadowing.mdx │ ├── styling.mdx │ └── navigation │ ├── tabs.mdx │ └── sidebar.mdx ## Markdown updates The last step is to add the name of your tabs to the front matter of each markdown file that has tabs. ```markdown --- title: Sidebar tabs: ['Sidebar', 'Tabs'] --- ``` ### Tabs with apostrophes If your tab name contains an apostrophe, you only need to include the grammatically correct text in the frontmatter. Your file name and `nav-items.yaml` should **not** include the apostrophe. ```markdown --- title: Sidebar tabs: ['Sidebar', "What’s new"] --- ``` For the _"What’s new"_ tab above, the source file would be `whats-new.mdx`, and the path would look like `/guides/navigation/whats-new`. --- ## File: src/pages/guides/hosting.mdx --- title: Hosting Overview of different hosting options for sites built using the Carbon Gatsby theme --- When building sites using the Carbon Gatsby Theme, there are a number of different ways you can host your site. While the Carbon team does not have an opinionated stance on how you host your projects, these are some resources others have found helpful for hosting. ## GH Pages [GitHub Pages](https://pages.github.com/) pages is a simple, low maintenance approach to get your site hosted quickly. For internal sites, or sites with proprietary information. Regardless of whether your projects is external or internal, there are a few steps (see below) to allow your site to work with GitHub Pages. [Get started](https://www.gatsbyjs.org/docs/how-gatsby-works-with-github-pages/) --- ## File: src/pages/guides/MDX.mdx --- title: MDX date: 27 January 2021 --- export const Title = () => ( First line Second line ); MDX allows for certain things beyond what markdown is capable of. Content here will discuss using those features to augment or modify the default content layout. It's extremly important that for any rich text, or images represented through mark down, that they are left aligned. This is true even if they are within a component. Otherwise it will be processed as a regular string. ## Frontmatter You can declare frontmatter in your `.mdx` files to provide specific metadata for the theme to use. - `title`: Main page title: search results and SEO - `description`: SEO and search results - `date`: Enter a date that the page was last modified to be displayed at the bottom left corner of the page. Refer to the [IBM Style guide](https://www-03preprod.ibm.com/support/knowledgecenter/ibm_style/dates-and-times.html) for the correct syntax. - `keywords`: just SEO (optional) - `hiddenFromSearch`: if true, page will be excluded from search ```md --- title: Markdown keywords: 'ibm,carbon,gatsby,mdx,markdown' date: 27 January 2021 hiddenFromSearch: true --- ``` ## Smart quotes The theme has a remark for processing straight quotes, into 'smart' quotes (''). However, this plugin isn't able to process text used in custom MDX components. When using quotes in custom components, content authors should manually use ["smart quotes"](https://www.figma.com/design-systems/) to adhere to the IBM Design Language content guidelines. ## Custom title You can export a `Title` component in order to render a unique title for a single page. This is particularly useful for including line breaks at a specific location. **Note:** You still need to provide a regular string title to the frontmatter for search, navigation, and the HTML header title to work. ```mdx --- title: MDX --- export const Title = () => ( First line Second line ); ; ``` --- ## File: src/pages/guides/npm-scripts.mdx --- title: npm scripts Overview of scripts used to run and build sites using the Carbon Gatsby theme --- Sites built with the Carbon Gatsby theme starter come ready to go with some helpful npm scripts. You can run these commands by typing `yarn [command]` or `npm run [command]` ## Clean - **clean** - this is used to clean gatsby's cache and public directory. It should be used sparingly, only when you're experiencing weird errors or caching issues. ## Develop - **develop** - this is your primary for starting up your gatsby site for development - **develop:clean** - this is provided as a convenience; it first runs `clean` then `develop` ## Build - **build** - this is what you'll use to bundle your site. Gatsby will minimize your images and create a static, blazing fast site in your `public` directory - **serve** - this can be run to serve the bundle locally after running `build`. It can be used to debug locally if any issues are encountered durring build. - **build:clean** - this is a provided as a convenience, it first runs `clean` then `build` - **build:prefix** - this will append all of your links with a [`pathPrefix`](https://www.gatsbyjs.org/docs/path-prefix/) specified in your `gatsby-config.js` - **serve:prefix** - this will allow you to serve the file locally using a prefixed site built with `build:prefix` - **test:prefix** - this is provided as a convenience; it first runs `build:prefix` then `test:prefix` - **build:analyze** - this will run build while also running [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) to help debug bundle size issues --- ## File: src/pages/guides/shadowing.mdx --- title: Shadowing date: 24 June 2020 --- In the world of Gatsby themes, [component shadowing](https://www.gatsbyjs.org/blog/2019-04-29-component-shadowing/) is an extremely powerful way for developers to provide their _own_ components for the theme to use over the defaults. You can shadow any file that is processed by webpack. This includes sass files, mdx files, and the react components themselves. ## Caveats If you completely shadow a file you won’t get future updates to that individual file. These are some golden rules to make sure you stay as close to the theme as possible and not forgo future updates. 1. Open a [quick issue](https://github.com/carbon-design-system/gatsby-theme-carbon/issues/new) in the gatsby-theme-carbon repo to make sure we’re not working on your change. 1. Shadow as few files as you can to achieve your goal. If you can shadow just a single file, that’s ideal. 1. If you do end up shadowing a component, please tell us! We might use it to inform future development. ## Shadowing basics In order to shadow a component in the theme, all you need to do is place a file in the `src/gatsby-theme-carbon` in your project. The file should have the same name as the file you’re shadowing. In order to place your own title in the Header component: 1. Create a file at the same directory as the component you wish to shadow. Everything after `src/gatsby-theme-carbon/` refers to the [src directory of gatsby-theme-carbon](https://github.com/carbon-design-system/gatsby-theme-carbon/tree/main/packages/gatsby-theme-carbon/src). 1. Import the component you wish to shadow by providing the full url pointing at the component within the theme 1. Your component will **receive the same props** as the one you’re shadowing. You’ll can log those props to see if you’ll need any of them 1. Regardless, you should _ALWAYS_ spread the extra props into the original component, this allows the core component to function as needed. Even if it doesn’t receive any props now, it might in the future. 1. Provide your new, custom component as the default export ```jsx import React from 'react'; import Header from 'gatsby-theme-carbon/src/components/Header'; const CustomHeader = (props) => (
Gatsby theme Carbon
); export default CustomHeader; ``` ## Components you’ll need to shadow We’ve already provided pre-shadowed, dummy components however these are the ones you’ll definitely need to shadow. | Component | Path | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | ResourceLinks | [`src/gatsby-theme-carbon/components/LeftNav/ResourceLinks.js`](https://github.com/carbon-design-system/gatsby-theme-carbon/blob/main/packages/example/src/gatsby-theme-carbon/components/LeftNav/ResourceLinks.js) | The bottom links on the SideNav, pass `shouldOpenNewTabs` to open links externally | | Footer | [`src/gatsby-theme-carbon/components/Footer.js`](https://github.com/carbon-design-system/gatsby-theme-carbon/blob/main/packages/example/src/gatsby-theme-carbon/components/Footer.js) | The links and content at the bottom of each page | | Header | [`src/gatsby-theme-carbon/components/Header.js`](https://github.com/carbon-design-system/gatsby-theme-carbon/blob/main/packages/example/src/gatsby-theme-carbon/components/Header.js) | The text in the top left corner of the UI Shell | --- ## File: src/pages/guides/sketch-kit.mdx --- title: Gatsby Sketch Kit Sketch kit of all components, patterns, and sample layouts that have been developed by teams within the IBM ecosystem. --- For anyone working on a Gatsby-themed site, this updated Sketch kit has all the components, patterns, and sample layouts that have been developed by teams within the IBM ecosystem. The Sketch kit is a great resource for designers working on new pages for PAL sites or any other sites using the Gatsby theme. ## Resources --- ## File: src/pages/guides/styling.mdx --- title: Styling Guide for adding site-specific styles and targeting theme components --- The carbon theme uses Sass to take advantage of the carbon-components styles and variables while authoring novel components. In addition, we use css modules to ensure we don’t collide with devs and make sure our components are portable and shadowable. ## Local Styles For your application’s local styles, you can just import your style sheet [directly into a `gatsby-browser.js`](https://www.gatsbyjs.org/docs/global-css/#adding-global-styles-without-a-layout-component) file at the root of your project. You can also use sass modules like we do in the theme, this would make it easier for you to share your component with other theme consumers down the line. Every Sass file in your project automatically has access to the the following carbon resources: - colors – `background: carbon--gray-10;` - spacing - `margin: $spacing-05;` - theme-tokens - `color: $text-01;` - motion - `transition: all $duration--moderate-01 motion(entrance, productive);` - typography - `@include carbon--type-style('body-long-01');` ## Targeting theme components We reserve the right to change classes between major releases. Use this strategy at your own risk. Theme component classes have a hash of their styles tacked on to the end. This is both to prevent collisions, and also to prevent sneaky breaking changes to your styles if we update the class underneath you and you were relying on our styles. However, you can target the classes without the hash by using a [partial selector](https://css-tricks.com/almanac/selectors/a/attribute/): ```scss [class*='Banner-module--column'] { color: $text-04; } ``` This will match the class that starts with `Banner-module--column` and would be immune to any changes to the hash. We may at some point remove the hash if this becomes an issue.