Move Documentation components to theme #3170
Conversation
rogermparent
changed the title
| const { getItemByPath } = require('../../src/utils/shared/sidebar') | ||
| const { | ||
| getItemByPath | ||
| } = require('../../plugins/gatsby-theme-iterative-docs/src/utils/shared/sidebar') |
There was a problem hiding this comment.
Since these aren't webpacked, the imports will have to stay relative until the theme is a real package, which is the next step.
| module.exports = ({ remark }) => { | ||
| const plugins = [] | ||
| if (remark) { | ||
| plugins.push({ | ||
| resolve: 'gatsby-transformer-remark', | ||
| options: { | ||
| plugins: [ | ||
| 'gatsby-remark-embedder', | ||
| { | ||
| resolve: 'gatsby-remark-prismjs', | ||
| options: { | ||
| noInlineHighlight: true, | ||
| languageExtensions: [ | ||
| { | ||
| language: 'text', | ||
| definition: {} | ||
| } | ||
| ] | ||
| } | ||
| }, | ||
| { | ||
| resolve: 'gatsby-remark-smartypants', | ||
| options: { | ||
| quotes: false | ||
| } | ||
| }, | ||
| { | ||
| resolve: 'gatsby-remark-embed-gist', | ||
| options: { | ||
| includeDefaultCss: true | ||
| } | ||
| }, | ||
| 'gatsby-remark-relative-images', | ||
| 'gatsby-remark-copy-linked-files', | ||
| 'gatsby-remark-external-links', | ||
| { | ||
| resolve: 'gatsby-remark-autolink-headers', | ||
| options: { | ||
| enableCustomId: true, | ||
| isIconAfterHeader: true | ||
| } | ||
| }, | ||
| { | ||
| resolve: 'gatsby-remark-images', | ||
| options: { | ||
| withWebp: true | ||
| } | ||
| }, | ||
| 'gatsby-remark-responsive-iframe' | ||
| ] | ||
| } | ||
| }) | ||
| } | ||
| return { | ||
| plugins | ||
| } | ||
| } |
There was a problem hiding this comment.
Reimplemented #3143
There was a problem hiding this comment.
Is there any website where we don't use remark plugins?
There was a problem hiding this comment.
iterative.ai doesn't, and likely won't, but it also wouldn't be using this theme. Also, cml.dev doesn't use the custom local remark plugins that dvc.org does, though it'll probably want to in the future.
| exports.onCreateWebpackConfig = ({ actions }) => { | ||
| actions.setWebpackConfig({ | ||
| resolve: { | ||
| alias: { | ||
| [path.resolve(__dirname, 'sidebar')]: path.resolve( | ||
| 'src', | ||
| 'gatsby-theme-iterative-docs', | ||
| 'sidebar' | ||
| ), | ||
| [path.resolve(__dirname, 'redirects')]: path.resolve( | ||
| 'src', | ||
| 'gatsby-theme-iterative-docs', | ||
| 'redirects' | ||
| ) | ||
| } | ||
| } | ||
| }) | ||
| } |
There was a problem hiding this comment.
The meat and potatoes to getting sidebar resolution working: this is similar to theme shadowing within Gatsby and uses the same directory structure on the consumer end, but the actual node files in the same location allow gatsby-node and other pure node modules to work with the same imports, and so allowing the modules that import these to be used in both environments, enabling the utils/shared modules to work even in an external module.
| export interface IPaginatorPageInfo { | ||
| currentPage: number | ||
| nextPage?: string | ||
| previousPage?: string | ||
| } | ||
|
|
There was a problem hiding this comment.
We need this interface but not the rest of Paginator
| @@ -2,7 +2,7 @@ import React from 'react' | |||
|
|
|||
| import MainLayout from '../MainLayout' | |||
| import DefaultSEO from './DefaultSEO' | |||
| import DocumentationLayout from '../Documentation/Layout' | |||
| import DocumentationLayout from '../DocumentationLayout' | |||
There was a problem hiding this comment.
We took the rest of the Documentation component but left Documentation/Layout behind and promoted it to its own standalone component.
Taking this into the theme would mean a lot more components the layout depends on would have to be pulled in, but this layout actually isn't very closely coupled with the rest of the Documentation component so breaking it apart works nicely.
| "paths": { | ||
| "gatsby-theme-iterative-docs/*": [ | ||
| "./plugins/gatsby-theme-iterative-docs/*" | ||
| ] | ||
| } |
There was a problem hiding this comment.
This enables tsc linting to work with the faked package imports, and will have to be removed once the theme becomes a real package.
| import React from 'react' | ||
|
|
||
| import MainLayout, { LayoutComponent, LayoutModifiers } from '../MainLayout' | ||
| import ThemeDocumentationLayout from 'gatsby-theme-iterative-docs/src/components/Documentation/Layout' | ||
|
|
||
| const Layout: LayoutComponent = ({ children, ...restProps }) => { | ||
| const { | ||
| location: { pathname } | ||
| } = restProps | ||
|
|
||
| return ( | ||
| <MainLayout | ||
| {...restProps} | ||
| modifiers={[LayoutModifiers.Wide, LayoutModifiers.Collapsed]} | ||
| > | ||
| <ThemeDocumentationLayout currentPath={pathname}> | ||
| {children} | ||
| </ThemeDocumentationLayout> | ||
| </MainLayout> | ||
| ) | ||
| } | ||
|
|
||
| export default Layout |
There was a problem hiding this comment.
In the latest iteration, I noticed the inner part of DocumentationLayout is pretty necessary to make the whole thing work, but thankfully only MainLayout pulls in a bunch of website dependencies so it can be easily broken off here.
Here's hoping it stays that way on merge! |
rogermparent
had a problem deploying
to
dvc-org-add-components--98uvhr
|
There was one build where images were broken in docs, but it seemed to clear up after a cache clear. I'll try another cached build and see if it happens again, otherwise I'll merge. Looks like it was fixed! I'll keep an eye on master just in case. |
* Move sidebar logic to theme * Split sidebar normalization and utils and import via shadowing * Fix usage of findChildWithSource * Fix lint-ts errors * Move comment normalized item definition to d.ts * Update and export INormalizedSidebarItem and use it in SidebarMenu * Add suppressable default gatsby-transformer-remark definition * Remove resolve-sidebar since local remark plugins are dvc.org only * Remove resolve-sidebar since local remark plugins are dvc.org only * Return src/components to master * Add alias for local theme * Roughly move doc components to theme * Revert to master package.json * Remove unused normalize sidebar module * Re-fix package.json and change test imports * stylelint --fix * Move Page and DocumentationLayout from theme to site * Fix svg imports * Remove unused layout components * stylelint fix * Extract github link function and repo constant to more easily overridable files * Remove unnecessary shadowed files since webpack override is in place * Remove unused constants file * Revert "Remove unused constants file" This reverts commit b07ca1b. * Remove actual unused constants file * Use theme-based Link component * Move core part of Documentation layout into theme * Rename sidebar test block to something more descriptive of its contents * Break apart docs sidebar and move it into theme * Add missing import
This PR is a bottom-up moving of the
Documentationcomponent, and any components it depends on (and there's a lot) to thegatsby-theme-iterative-docsplugin.