diff --git a/README.md b/README.md index 2077fdfb..a7299557 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ - @neato/guider - beautiful documentation generator framework based on nextjs (ALPHA) ## Upcoming packages -- @neato/router - http router based on fastify () -- @neato/orm - mini ORM, it's just migrations, mapper and a query builder -- @neato/email - JSX based email template engine +- @neato/router - http router based on fastify - @neato/auth - fully fledged authentication system, including permissions +- @neato/jobs - persistent job queue +- @neato/log - simple logger with good pretty defaults diff --git a/apps/docs/components/showcase-card.tsx b/apps/docs/components/showcase-card.tsx index 41ebdcb4..d59e1883 100644 --- a/apps/docs/components/showcase-card.tsx +++ b/apps/docs/components/showcase-card.tsx @@ -69,14 +69,13 @@ export function ShowcaseCard(props: { showcase: ShowcaseType }) {
- {props.showcase.title} - + className="block hover:opacity-75 border-line border aspect-video w-full bg-bgLightest mb-6 rounded-xl overflow-hidden" + style={{ + backgroundImage: `url(${props.showcase.imageUrl})`, + backgroundPosition: 'center', + backgroundSize: 'cover', + }} + />

{props.showcase.title} diff --git a/apps/docs/components/themer.tsx b/apps/docs/components/themer.tsx index c5eabe8a..cd336004 100644 --- a/apps/docs/components/themer.tsx +++ b/apps/docs/components/themer.tsx @@ -1,10 +1,11 @@ +import type { ThemeColorStoreColors } from '@neato/guider/client'; import { Button } from '@neato/guider/client'; import classNames from 'classnames'; import type { ReactNode } from 'react'; -import React, { useState, useCallback } from 'react'; +import React, { useState, useCallback, useRef } from 'react'; import type { HsbColor } from 'hooks/color-select'; import { hsbToColorToString, useColorSelect } from 'hooks/color-select'; -import { useGuideThemePicker } from 'hooks/use-guider-theme-picker'; +import { makeColors, useGuideThemePicker } from 'hooks/use-guider-theme-picker'; import styles from './themer.module.css'; function ThemeColor(props: { @@ -89,6 +90,7 @@ function ColorPicker(props: { export function ThemeColorPicker(props: { colors: [HsbColor, HsbColor]; setColors: (n: [HsbColor, HsbColor]) => void; + onGetCode?: (colors: [HsbColor, HsbColor]) => void; }) { const { colors, setColors } = props; const [selectedColor, setSelectedColor] = useState(0); @@ -128,27 +130,72 @@ export function ThemeColorPicker(props: { />
- +
); } -export function Themer() { +export function Themer(props: { + onGetCode?: (colors: ThemeColorStoreColors) => void; +}) { const [colors, setColors] = useGuideThemePicker(); + const onGetCode = useCallback( + (c: [HsbColor, HsbColor]) => { + props.onGetCode?.(makeColors(c)); + }, + [props.onGetCode], + ); - return ; + return ( + + ); } export function ThemerContainer(props: { children?: ReactNode }) { + const ref = useRef(null); + const tokenRef = useRef(null); + const [hasCode, setHasCode] = useState(false); + const onGetCode = useCallback((c: ThemeColorStoreColors) => { + if (tokenRef.current) { + tokenRef.current.innerText = JSON.stringify(c, null, 2); + return; + } + if (ref.current) { + setHasCode(true); + const token = [ + ...ref.current.querySelectorAll('code [data-line] span'), + ].find( + (el) => (el as HTMLSpanElement).innerText === 'CODE', + ) as HTMLSpanElement | null; + if (token) { + tokenRef.current = token; + token.innerText = JSON.stringify(c, null, 2); + } + } + }, []); + return ( -
-
- {props.children} -
-
-
- +
+
+
+ {props.children} +
+
+
+ +
diff --git a/apps/docs/hooks/use-guider-theme-picker.ts b/apps/docs/hooks/use-guider-theme-picker.ts index 4d822bf4..863e090e 100644 --- a/apps/docs/hooks/use-guider-theme-picker.ts +++ b/apps/docs/hooks/use-guider-theme-picker.ts @@ -1,13 +1,68 @@ import type { ThemeColorStoreColors } from '@neato/guider/client'; import { useGuiderTheme } from '@neato/guider/client'; import { useCallback, useEffect, useState } from 'react'; +import Color from 'color'; import type { HsbColor } from './color-select'; import { hsbToColorToString } from './color-select'; -function makeColors(c: [HsbColor, HsbColor]): ThemeColorStoreColors { +const clamp = (max: number, min: number, n: number) => + Math.max(min, Math.min(max, n)); + +function getContrastPoint(color: Color): [number, number] { + if (color.isDark()) return [100, 0]; + return [0, 100]; +} + +function getDistanceToContrastPoint(bgColor: Color, color: Color): number { + const contrastPoint = getContrastPoint(bgColor); + return Math.sqrt( + Math.pow(contrastPoint[0] - color.value(), 2) + + Math.pow(contrastPoint[1] - color.saturationl(), 2), + ); +} + +function moveColorToContrastPoint( + bgColor: Color, + color: Color, + amount: number, +): Color { + const contrastPoint = getContrastPoint(bgColor); + const length = getDistanceToContrastPoint(bgColor, color); + const ratio = amount / length; + const currentPoint = [color.value(), color.saturationl()]; + const newX = currentPoint[0] + (contrastPoint[0] - currentPoint[0]) * ratio; + const newY = currentPoint[1] + (contrastPoint[1] - currentPoint[1]) * ratio; + return color.value(clamp(100, 0, newX)).saturationl(clamp(100, 0, newY)); +} + +function moveRatioColorToContrastPoint( + bgColor: Color, + color: Color, + ratio: number, +): Color { + const distance = getDistanceToContrastPoint(bgColor, color); + return moveColorToContrastPoint(bgColor, color, distance * ratio); +} + +export function makeColors(c: [HsbColor, HsbColor]): ThemeColorStoreColors { + const primary = Color(hsbToColorToString(c[0])); + const bg = Color(hsbToColorToString(c[1])); + const text = moveRatioColorToContrastPoint(bg, bg, 0.7); + return { - primary: hsbToColorToString(c[0]), - background: hsbToColorToString(c[1]), + primary: primary.hex(), + primaryLighter: moveColorToContrastPoint(primary, primary, -30).hex(), + primaryDarker: moveColorToContrastPoint(primary, primary, 30).hex(), + + background: bg.hex(), + backgroundLighter: moveColorToContrastPoint(bg, bg, 8).hex(), + backgroundLightest: moveColorToContrastPoint(bg, bg, 16).hex(), + backgroundDarker: moveColorToContrastPoint(bg, bg, -8).hex(), + line: moveColorToContrastPoint(bg, bg, 25).hex(), + + text: text.hex(), + textLighter: moveColorToContrastPoint(bg, text, 10).hex(), + textHighlight: bg.isDark() ? '#fff' : '#000', }; } diff --git a/apps/docs/package.json b/apps/docs/package.json index 88f2aa89..78fdfbc3 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -20,6 +20,7 @@ "@repo/eslint-config": "workspace:*", "@repo/prettier-config": "workspace:*", "@repo/typescript-config": "workspace:*", + "@types/color": "^3.0.6", "@types/react": "18.2.56", "autoprefixer": "^10.4.17", "postcss": "^8.4.37", @@ -28,6 +29,7 @@ "dependencies": { "@neato/guider": "workspace:*", "classnames": "^2.5.1", + "color": "^4.2.3", "next": "^14.1.0", "react": "^18.2.0", "react-dom": "^18.2.0" diff --git a/apps/docs/pages/docs/config/index.tsx b/apps/docs/pages/docs/config/index.tsx index 0efcb602..ace9cd0a 100644 --- a/apps/docs/pages/docs/config/index.tsx +++ b/apps/docs/pages/docs/config/index.tsx @@ -18,7 +18,7 @@ export default function LandingPage() { diff --git a/apps/docs/pages/docs/guider/api-reference/components/guider-content-footer.mdx b/apps/docs/pages/docs/guider/api-reference/components/guider-content-footer.mdx new file mode 100644 index 00000000..eb1a768c --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/components/guider-content-footer.mdx @@ -0,0 +1,19 @@ +# `` + +React component that will show the currently configured content footer. + +It respects configured `contentFooter` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials). + + +## Example + +```tsx + +``` + + +## Reference + +```tsx +function GuiderContentFooter(): ReactNode; +``` diff --git a/apps/docs/pages/docs/guider/api-reference/components/guider-header.mdx b/apps/docs/pages/docs/guider/api-reference/components/guider-header.mdx index 6bdc3bbb..276e9275 100644 --- a/apps/docs/pages/docs/guider/api-reference/components/guider-header.mdx +++ b/apps/docs/pages/docs/guider/api-reference/components/guider-header.mdx @@ -1,5 +1,21 @@ # `` - -This article is a stub, please help by contributing to the docs. - +React component that will show the currently configured navigation partial. + +It respects configured `navigation` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials). + + +## Example + +```tsx +
+ // [!code focus] +
+``` + + +## Reference + +```tsx +function GuiderHeader(): ReactNode; +``` diff --git a/apps/docs/pages/docs/guider/api-reference/components/guider-layout.mdx b/apps/docs/pages/docs/guider/api-reference/components/guider-layout.mdx index 80acf707..a77ee0c6 100644 --- a/apps/docs/pages/docs/guider/api-reference/components/guider-layout.mdx +++ b/apps/docs/pages/docs/guider/api-reference/components/guider-layout.mdx @@ -1,5 +1,61 @@ # `` - -This article is a stub, please help by contributing to the docs. - +React component that will show the currently configured layout partial. + +It respects configured `layout` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials). + +The primary use of this component is to make a non-MDX page look like an MDX page. Don't use it if you're already in an MDX File. + +## Example + +```tsx + +

Custom page

+

This is a custom page that doesn't use MDX

+ +``` + + +## Reference + +```tsx +function GuiderLayout(props); +``` + + The props for this component. Every prop is optional. + + + + The meta configuration, see [the meta file reference](../meta/structure.mdx) for the contents. + + + An excerpt of the page, used in meta tags for SEO. + + + The headings of the page, first depth 1 heading is used as page title for SEO. + + This is also to display the table of contents. + + + + The depth of the heading. Equals to the amount of hashtags of the heading. + + + Text content of the heading. + + + Extra data associated with the heading. + + + + The ID of the heading. + + + + + + + The children of the react component, it will be displayed as the page contents. + + + diff --git a/apps/docs/pages/docs/guider/api-reference/components/guider-logo.mdx b/apps/docs/pages/docs/guider/api-reference/components/guider-logo.mdx new file mode 100644 index 00000000..1dbb8c07 --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/components/guider-logo.mdx @@ -0,0 +1,19 @@ +# `` + +React component that will show the currently configured logo. + +It respects configured `logo` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials). + + +## Example + +```tsx + +``` + + +## Reference + +```tsx +function GuiderLogo(): ReactNode; +``` diff --git a/apps/docs/pages/docs/guider/api-reference/components/guider-page-footer.mdx b/apps/docs/pages/docs/guider/api-reference/components/guider-page-footer.mdx new file mode 100644 index 00000000..28ff6ca4 --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/components/guider-page-footer.mdx @@ -0,0 +1,19 @@ +# `` + +React component that will show the currently configured page footer. + +It respects configured `pageFooter` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials). + + +## Example + +```tsx + +``` + + +## Reference + +```tsx +function GuiderPageFooter(): ReactNode; +``` diff --git a/apps/docs/pages/docs/guider/api-reference/components/guider-sidebar.mdx b/apps/docs/pages/docs/guider/api-reference/components/guider-sidebar.mdx index 0c77caaa..cf47f551 100644 --- a/apps/docs/pages/docs/guider/api-reference/components/guider-sidebar.mdx +++ b/apps/docs/pages/docs/guider/api-reference/components/guider-sidebar.mdx @@ -1,5 +1,21 @@ # `` - -This article is a stub, please help by contributing to the docs. - +React component that will show the currently configured sidebar partial. + +It respects configured `sidebar` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials). + + +## Example + +```tsx +
+ // [!code focus] +
+``` + + +## Reference + +```tsx +function GuiderSidebar(): ReactNode; +``` diff --git a/apps/docs/pages/docs/guider/api-reference/components/guider-toc.mdx b/apps/docs/pages/docs/guider/api-reference/components/guider-toc.mdx index 065bf973..f0213840 100644 --- a/apps/docs/pages/docs/guider/api-reference/components/guider-toc.mdx +++ b/apps/docs/pages/docs/guider/api-reference/components/guider-toc.mdx @@ -1,5 +1,21 @@ # `` - -This article is a stub, please help by contributing to the docs. - +React component that will show the currently configured table of contents. + +It respects configured `toc` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials). + + +## Example + +```tsx +
+ // [!code focus] +
+``` + + +## Reference + +```tsx +function GuiderToc(): ReactNode; +``` diff --git a/apps/docs/pages/docs/guider/api-reference/functions/create-not-found-page.mdx b/apps/docs/pages/docs/guider/api-reference/functions/create-not-found-page.mdx index 83f39fd5..125a51d2 100644 --- a/apps/docs/pages/docs/guider/api-reference/functions/create-not-found-page.mdx +++ b/apps/docs/pages/docs/guider/api-reference/functions/create-not-found-page.mdx @@ -1,5 +1,23 @@ # `createNotFoundPage()` - -This article is a stub, please help by contributing to the docs. - +This function creates a premade 404 page. + +You don't have to use this 404 page, it does nothing special. Feel free to make your own. + + + This has be put in `/pages/404.tsx` to work, you can't choose a different location or it won't work. + + + +## Example + +```tsx title="/pages/404.tsx" +export default createNotFoundPage(); +``` + + +## Reference + +```tsx +function createNotFoundPage(); +``` diff --git a/apps/docs/pages/docs/guider/api-reference/functions/create-redirect.mdx b/apps/docs/pages/docs/guider/api-reference/functions/create-redirect.mdx index 93a18b20..3091a724 100644 --- a/apps/docs/pages/docs/guider/api-reference/functions/create-redirect.mdx +++ b/apps/docs/pages/docs/guider/api-reference/functions/create-redirect.mdx @@ -1,5 +1,27 @@ # `createRedirect()` - -This article is a stub, please help by contributing to the docs. - +This utility function is an easy way to make redirects work in static site generation mode. + + +## Example + +```tsx title="/pages/index.tsx" +export default createRedirect({ to: '/docs/guides' }); +``` + + +## Reference + +```tsx +function createRedirect(options); +``` + + + Options for the redirect. + + + + Where the user gets redirected to when it renders this page. + + + diff --git a/apps/docs/pages/docs/guider/api-reference/functions/use-guider-page.mdx b/apps/docs/pages/docs/guider/api-reference/functions/use-guider-page.mdx index d48f0833..8421cc75 100644 --- a/apps/docs/pages/docs/guider/api-reference/functions/use-guider-page.mdx +++ b/apps/docs/pages/docs/guider/api-reference/functions/use-guider-page.mdx @@ -1,5 +1,105 @@ # `useGuiderPage()` - -This article is a stub, please help by contributing to the docs. - +This React hook is the way to hook into Guider internals for the current page. + + +## Example + +```tsx +function useIsTocEnabled() { + const guider = useGuiderPage(); + const tocState = guider.settings.tocState; + return tocState; +} +``` + + +## Reference + +```tsx +function useGuiderPage(): GuiderPageContext; +``` + + The context for a Guider page, including the page meta data. + + + + The currently active site. + + See [the `useGuider()` page](./use-guider.mdx) for more info. + + + The currently active directory. + + See [the `useGuider()` page](./use-guider.mdx) for more info. + + + The currently active layout. + + See [the `useGuider()` page](./use-guider.mdx) for more info. + + + The fully populated layout settings, all defaults are merged into it (so no optional properties). + + Read more [about layout settings](../theme/settings.mdx). + + See [the `useGuider()` page](./use-guider.mdx) for more info. + + + A list of the contents of your `_meta.json` files. + + See [the `useGuider()` page](./use-guider.mdx) for more info. + + + Data for the current page content. + + + + The metadata for this page. + + + + The site field in the Frontmatter + + + The directory field in the Frontmatter + + + The layout field in the Frontmatter + + + The title field in the Frontmatter + + + The description field in the Frontmatter + + + + + The headings in the page content in order of appearance. + + + + The depth of the heading. Equals to the amount of hashtags of the heading. + + + Text content of the heading. + + + Extra data associated with the heading. + + + + The ID of the heading. + + + + + + + An first paragraph of the page content. + + + + + diff --git a/apps/docs/pages/docs/guider/api-reference/functions/use-guider.mdx b/apps/docs/pages/docs/guider/api-reference/functions/use-guider.mdx index 0762a695..50c68313 100644 --- a/apps/docs/pages/docs/guider/api-reference/functions/use-guider.mdx +++ b/apps/docs/pages/docs/guider/api-reference/functions/use-guider.mdx @@ -1,5 +1,202 @@ # `useGuider()` - -This article is a stub, please help by contributing to the docs. - +This React hook is the way to hook into Guider internals. It can give you information about the entire Guider instance. + + +## Example + +```tsx +function useIsTocEnabled() { + const guider = useGuider(); + const tocState = guider.settings.tocState; + return tocState; +} +``` + + +## Reference + +```tsx +function useGuider(metaConf): GuiderContext; +``` + + + Optional meta config overwrite, it will fall back on what is configured in `_meta.json` files. + + This does **not** account for FrontMatter config. Use `useGuiderPage()` ([Check here](../functions/use-guider-page.mdx)) if you need Frontmatter accounted for. + + + + The context for a Guider page. + + + + The currently active site. + + + + The ID of the site, this is used for referencing the site in other parts of your configuration, for example in `_meta.json` files. + + + List of items shown in the top navigation bar. + + + List of links to show in the tabs section of the header. + + + List of links to show in the dropdown section of the header. You can only specify `link()` and `group()` (groups can only hold other links). + + + The meta data shown for all pages associated with the site. + + + A repository identifier, if specified a GitHub widget with the star count and fork count is displayed on the right side of the header. + + The identifier needs to be either `{ORG_NAME}/{REPO_NAME}` or `{USER_NAME}/{REPO_NAME}`. For example: `mrjvs/neatojs`. + + + A text based logo to show top left of the header. If not specified, a placeholder is shown. + + You can also overwrite the logo, for example to show an image. Read more [about overwriting the logo](../../guides/config/theming.mdx#changing-the-logo). + + + + Text to display in the logo. + + + Link to make the logo redirect to when clicked. If not specified, the logo is not clickable. + + + + + The default layout to show for all pages associated with this site. + + + List of layouts for this site. + + + + The ID of the layout + + + The populated layout settings for this layout, read more [about layout settings](../theme/settings.mdx). + + This is preresolved, but you shouldn't use it directly. Use the returned settings on `GuiderContext.settings` instead. + + + + + The layout settings for this site, read more [about layout settings](../theme/settings.mdx). + + This is preresolved, but you shouldn't use it directly. Use the returned settings on `GuiderContext.settings` instead. + + + List of directories for this site, read more [about directories here](../theme/directory.mdx). + + + + The ID of the directory + + + The ID of the layout that needs to be shown for pages in this directory. + + + The populated layout settings for this directory, read more [about layout settings](../theme/settings.mdx). + + This is preresolved, but you shouldn't use it directly. Use the returned settings on `GuiderContext.settings` instead. + + + List of links to show in the sidebar. + + + + + Options for the content footer (the footer placed right below the content). + + The visibility of the content footer is not controlled by the settings. To control the visibility of the footer, check [the footer page](../../guides/advanced/footer.mdx) for more info. + + + + Text shown in the content footer, by default it will be a copyright notice. + + + List of social media links shown in the content footer. Check [the social() page](../theme/social.mdx) for usage. + + + Base URL of your Git repository, it will be used to show a "Edit on GitHub" link. Leave undefined if you don't want such a link. + + Check [this page](../../guides/advanced/footer.mdx#configuring-the-content-footer) for information on how to configure it. + + + + + Options for the page footer (the footer placed at the very bottom of the page). + + The visibility of the page footer is not controlled by the settings. To control the visibility of the footer, check [the footer page](../../guides/advanced/footer.mdx) for more info. + + + + Text shown in the page footer, it will be blank by default. + + + + + + + The currently active directory. + + + + The ID of the directory + + + The ID of the layout that needs to be shown for pages in this directory. + + + The populated layout settings for this directory, read more [about layout settings](../theme/settings.mdx). + + This is preresolved, but you shouldn't use it directly. Use the returned settings on `GuiderContext.settings` instead. + + + List of links to show in the sidebar. + + + + + The currently active layout. + + + + The ID of the layout + + + The populated layout settings for this layout, read more [about layout settings](../theme/settings.mdx). + + This is preresolved, but you shouldn't use it directly. Use the returned settings on `GuiderContext.settings` instead. + + + + + The fully populated layout settings, all defaults are merged into it (so no optional properties). + + Read more [about layout settings](../theme/settings.mdx). + + + A list of the contents of your `_meta.json` files. + + + + The site path that this `_meta.json` file belongs to. + + + The resolved meta file configuration, it accounts for all meta files that are above it. So you can use this if it's the most specific path. + + Read more [about meta files](../meta/structure.mdx). + + + The raw contents of the `_meta.json` file. Can be used for custom properties. + + + + + diff --git a/apps/docs/pages/docs/guider/api-reference/meta/structure.mdx b/apps/docs/pages/docs/guider/api-reference/meta/structure.mdx index 1b30aef3..e51d54ee 100644 --- a/apps/docs/pages/docs/guider/api-reference/meta/structure.mdx +++ b/apps/docs/pages/docs/guider/api-reference/meta/structure.mdx @@ -1,5 +1,27 @@ # Structure of `_meta.json` - -This article is a stub, please help by contributing to the docs. - +Find out the structure of the `_meta.json` file. + + +## The file + +The `_meta.json` file can created and placed in any folder in the `/pages` directory. + +The meta file will be applied to all routes and child routes of the folder. + + + All fields inside the meta file can also be specified in the Frontmatter of a page, so you don't need to make a meta file for a single page. + + + +## Reference + + + Which site the page(s) belong to, defaults to the first (or only) site. + + + Which directory the page(s) is in, defaults to the first directory of the selected site. + + + Which layout the page(s) should be displayed with, defaults to the layout with ID `default`. + diff --git a/apps/docs/pages/docs/guider/api-reference/theme/component.mdx b/apps/docs/pages/docs/guider/api-reference/theme/component.mdx index f6e46a66..885b4985 100644 --- a/apps/docs/pages/docs/guider/api-reference/theme/component.mdx +++ b/apps/docs/pages/docs/guider/api-reference/theme/component.mdx @@ -1,5 +1,55 @@ # `component()` - -This article is a stub, please help by contributing to the docs. - +Allows using a custom component for a navigation item. Useful if you want to add custom functionality to your sidebars (or other navigation structures). + + +## Example + +```tsx title="theme.config.tsx" +function DonateButton() { + return ( +
+ +
+ ) +} + +export default defineTheme({ + directories: [ + directory("dir-a", { + sidebar: [ + link("Home", "/home"), + component(() => ) + ] + }) + ], +}) +``` + + +## Reference + +```tsx +function component(comp); +``` + + + A function that returns JSX. You can run React hooks in here. + + + +## Reference - Options + +```tsx +function component(options); +``` + + + Options for this custom component item. + + + + A function that returns JSX. You can run React hooks in here. + + + diff --git a/apps/docs/pages/docs/guider/api-reference/theme/define-theme.mdx b/apps/docs/pages/docs/guider/api-reference/theme/define-theme.mdx index 1756f30a..ed58a434 100644 --- a/apps/docs/pages/docs/guider/api-reference/theme/define-theme.mdx +++ b/apps/docs/pages/docs/guider/api-reference/theme/define-theme.mdx @@ -1,5 +1,36 @@ # `defineTheme()` - -This article is a stub, please help by contributing to the docs. - +The only purpose `defineTheme()` has is to make a theme configuration. The output of this function must be +the default export of the theme file. + +## Example + +```tsx title="theme.config.tsx" +export default defineTheme({ + directories: [], +}) + +// or a list of sites +export default defineTheme([ + site('site-a', { + directories: [], + }), + site('site-b', { + directories: [], + }) +]) +``` + + +## Reference + +```tsx +function defineTheme(options); +``` + + + To make a theme, you can either provide a site object or a list of `SiteComponent`. + The site objects can be made using [the site function](./site.mdx). The same page also lists the options for a site. + + If you use a site object, the site ID will be set to `main`. + diff --git a/apps/docs/pages/docs/guider/api-reference/theme/directory.mdx b/apps/docs/pages/docs/guider/api-reference/theme/directory.mdx index 90bc7acf..9794436d 100644 --- a/apps/docs/pages/docs/guider/api-reference/theme/directory.mdx +++ b/apps/docs/pages/docs/guider/api-reference/theme/directory.mdx @@ -1,5 +1,49 @@ # `directory()` - -This article is a stub, please help by contributing to the docs. - +Directories hold a site's sidebar navigation items. + + +## Example + +```tsx title="theme.config.tsx" +export default defineTheme({ + directories: [ + directory("dir-a", { + sidebar: [ + link("Home", "/home"), + ] + }) + ], +}) +``` + + +## Reference + +```tsx +function directory(id, options); +``` + + + The ID of the directory - Can be anything and is only used for referencing in meta files or similar. + + + + All options of the directory. + + + + The default layout to show for all pages associated with this directory. Defaults to the layout for the site. + + + The layout settings for this directory, read more [about layout settings](./settings.mdx). + + The settings in this settings layer are applied last - overriding settings defined in sites and layouts. + + + List of links to show in the sidebar. You can specify `link()`, `link.nested()`, `separator()`, `component()`, `group()` (groups can hold all other types except for more groups). + + Read more about those on their respective documentation pages. + + + diff --git a/apps/docs/pages/docs/guider/api-reference/theme/group.mdx b/apps/docs/pages/docs/guider/api-reference/theme/group.mdx index adc1ce5a..d587c918 100644 --- a/apps/docs/pages/docs/guider/api-reference/theme/group.mdx +++ b/apps/docs/pages/docs/guider/api-reference/theme/group.mdx @@ -1,5 +1,57 @@ # `group()` - -This article is a stub, please help by contributing to the docs. - +A navigation group, can be used to categorize or group links. + + +## Example + +```tsx title="theme.config.tsx" +export default defineTheme({ + directories: [ + directory("dir-a", { + sidebar: [ + group("Guides", [ + link("Guide A", "/guides/a"), + link("Guide B", "/guides/b"), + ]), + ] + }) + ], +}) +``` + + +## Reference + +```tsx +function group(title, items); +``` + + + The title of the group. + + + + The navigation items inside of this group, the acceptable item types depends on which navigation area the group is in. + + + +## Reference - Options + +```tsx +function group(options); +``` + + + The options for this group. + + + + The title of the group. + + + + The navigation items inside of this group, the acceptable item types depends on which navigation area the group is in. + + + diff --git a/apps/docs/pages/docs/guider/api-reference/theme/link.mdx b/apps/docs/pages/docs/guider/api-reference/theme/link.mdx index 800154da..8de78ac3 100644 --- a/apps/docs/pages/docs/guider/api-reference/theme/link.mdx +++ b/apps/docs/pages/docs/guider/api-reference/theme/link.mdx @@ -1,5 +1,156 @@ # `link()` - -This article is a stub, please help by contributing to the docs. - +A standard link for your navigation items. You can also nest links. + +## Example + +```tsx title="theme.config.tsx" +export default defineTheme({ + directories: [ + directory("dir-a", { + sidebar: [ + link("Home", "/home"), + link.nested("Guides", [ + link("Guide A", "/guides/a"), + link("Guide B", "/guides/b"), + ]), + ] + }) + ], +}) +``` + + +## Reference - Link parameters + +```tsx +function link(title, to, options); +``` + + + The title of the link. + + + + Where the link goes to. For example: `/docs/guides/guide-a`. + + + + Extra options for this link. All fields are optional. + + + + The icon to display in the navigation item, choose from [icones](https://icones.js.org/). + + + If clicking the link should open a new tab or not. + + + If the active page check should check the exact page and not its child routes. Useful in the case where you have a homepage in navigation. + + + The display style of the link, can be `default` or `star`. + + + + + +## Reference - link options + +```tsx +function link(options); +``` + + + The options for this link. + + + + The title of the link. + + + Where the link goes to. For example: `/docs/guides/guide-a`. + + + The icon to display in the navigation item, choose from [icones](https://icones.js.org/). + + + If clicking the link should open a new tab or not. + + + If the active page check should check the exact page and not it's child routes. Useful in the case where you have a homepage in navigation. + + + The display style of the link, can be `default` or `star`. + + + + + +## Reference - nested link parameters + +```tsx +function link.nested(title, to, items); +``` + + + The title of the link. + + + + Where the link goes to. For example: `/docs/guides/guide-a`. + + + + The child items of the nested link. + + + +## Reference - nested link parameters without link + +```tsx +function link.nested(title, items); +``` + + + The title of the link. + + + + The child items of the nested link. + + + +## Reference - nested link options + +```tsx +function link.nested(options); +``` + + + The options for this nested link. + + + + The title of the link. + + + Where the link goes to. For example: `/docs/guides/guide-a`. + + + The child items of the nested link. + + + The icon to display in the navigation item, choose from [icones](https://icones.js.org/). + + + If clicking the link should open a new tab or not. + + + If the active page check should check the exact page and not it's child routes. Useful in the case where you have a homepage in navigation. + + + The display style of the link, can be `default` or `star`. + + + diff --git a/apps/docs/pages/docs/guider/api-reference/theme/separator.mdx b/apps/docs/pages/docs/guider/api-reference/theme/separator.mdx new file mode 100644 index 00000000..c57b45d5 --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/theme/separator.mdx @@ -0,0 +1,27 @@ +# `separator()` + +A separator, simply draws a line inbetween navigation items. + + +## Example + +```tsx title="theme.config.tsx" +export default defineTheme({ + directories: [ + directory("dir-a", { + sidebar: [ + link("Guide A", "/guides/a"), + separator(), + link("Guide B", "/guides/b"), + ] + }) + ], +}) +``` + + +## Reference + +```tsx +function separator(); +``` diff --git a/apps/docs/pages/docs/guider/api-reference/theme/seperator.mdx b/apps/docs/pages/docs/guider/api-reference/theme/seperator.mdx deleted file mode 100644 index 3845f3b3..00000000 --- a/apps/docs/pages/docs/guider/api-reference/theme/seperator.mdx +++ /dev/null @@ -1,5 +0,0 @@ -# `seperator()` - - -This article is a stub, please help by contributing to the docs. - diff --git a/apps/docs/pages/docs/guider/api-reference/theme/settings.mdx b/apps/docs/pages/docs/guider/api-reference/theme/settings.mdx new file mode 100644 index 00000000..709dd26a --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/theme/settings.mdx @@ -0,0 +1,69 @@ +# Layout settings + +Layout settings are the interface on which you modify your layout. + +All of these settings can be changed in any settings layer, [read more about settings layers](../../guides/advanced/customizing-layout.mdx). + + +## Example + +```tsx +settings: { + toc: false, + colors: { + primary: '#f76957', + } +} +``` + + +## About partials + +Partial settings work slightly differently than other settings: +- To overwrite a partial, pass in a function (e.g. `toc: () =>

hello

{:tsx}`). This will also **show** the partial. +- Set a partial to `true{:tsx}` to **show** the partial, but not change its contents (e.g. `toc: true{:tsx}`). +- Set a partial to `false{:tsx}` to **hide** the partial, but not change its contents (e.g. `toc: false{:tsx}`). +- To use the settings from the upper layer. Just don't set the settings (or set it to undefined). + +You can read more about layout partials in the [layout settings guide](../../guides/advanced/customizing-layout.mdx). + +When you overwrite a partial, you can use `useGuiderPage()` to get the current page information. ([Read more here](../functions/use-guider-page.mdx)). + + +## Reference + + + The table of contents partial. Check [this section](#about-partials) for information on how to use partials. + + + The sidebar partial. Check [this section](#about-partials) for information on how to use partials. + + + The navigation/header partial. Check [this section](#about-partials) for information on how to use partials. + + + The content footer partial. Check [this section](#about-partials) for information on how to use partials. + + + The page footer partial. Check [this section](#about-partials) for information on how to use partials. + + + The logo partial. Check [this section](#about-partials) for information on how to use partials. + + + The page layout partial. Check [this section](#about-partials) for information on how to use partials. + + + This partial cannot be hidden, the layout wraps the entire site. + + + + the background pattern settings, set it `flare` to have a nice shard of light on your page background. + + Just like partials, you can use `true` and `false` to show or hide the partial. + + + The layout colors, this is how you customize the theme colors. + + Discover the theme colors [in this guide](../../guides/config/theming.mdx#changing-colors). + diff --git a/apps/docs/pages/docs/guider/api-reference/theme/site-template.mdx b/apps/docs/pages/docs/guider/api-reference/theme/site-template.mdx new file mode 100644 index 00000000..fff776e6 --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/theme/site-template.mdx @@ -0,0 +1,29 @@ +# `siteTemplate()` + +Site templates can be used to make a reusuable instance of a site. You can use `Site.extends{:ts}` to utilize site templates. + + +## Example + +```tsx title="theme.config.tsx" +const baseTemplate = siteTemplate({ + // All sites that extend this template will have the "github" property set + github: "mrjvs/neatojs", +}) + +export default defineTheme({ + extends: [baseTemplate], + directories: [], +}) +``` + + +## Reference + +```tsx +function siteTemplate(options); +``` + + + This accepts the same options as a normal site would, see [the site function](./site.mdx) for the reference for those options. + diff --git a/apps/docs/pages/docs/guider/api-reference/theme/site.mdx b/apps/docs/pages/docs/guider/api-reference/theme/site.mdx index 4dc241c9..8fbbc776 100644 --- a/apps/docs/pages/docs/guider/api-reference/theme/site.mdx +++ b/apps/docs/pages/docs/guider/api-reference/theme/site.mdx @@ -1,5 +1,148 @@ # `site()` - -This article is a stub, please help by contributing to the docs. - +A site is an instance of root level configuration. If you need to modify navigation items, footers and alike, you'll be modifying a site. + +You can find more information on how to use sites effectively in [this guide](../../guides/advanced/multi-site.mdx). + + +## Example + +```tsx title="theme.config.tsx" +export default defineTheme([ + site('site-a', { + directories: [], + }), + site('site-b', { + directories: [], + }) +]) +``` + + +## Reference + +```tsx +function site(id, options); +``` + + + The ID of the site, this is used for referencing the site in other parts of your configuration, for example in `_meta.json` files. + + + + All options of the site. + + + + Extending of site templates, specified site templates get merged in the order they are passed in. + Meaning that the last specified site will have priority over the sites earlier in the array. + + Site templates can be made with `siteTemplate()`, more info [found here](./site-template.mdx). + + Read more about how to use templates in [this guide](../../guides/advanced/multi-site.mdx#site-templates). + + + List of items shown in the top navigation bar. You can only specify `separator()`, `link()` and `component()`. + Read more about those on their respective documentation pages. + + + List of links to show in the tabs section of the header. You can only specify `link()` and `component()`. + Read more about those on their respective documentation pages. + + The tabs section of the header only shows up if there are items in the array. + + + List of links to show in the dropdown section of the header. You can only specify `link()` and `group()` (groups can only hold other links). + Read more about those on their respective documentation pages. + + The dropdown section of the header only shows up if there are items in the array. + + + The meta data shown for all pages associated with the site. + + You can either specify an object for your meta data, which will follow the structure [defined here](https://github.com/garmeeh/next-seo?tab=readme-ov-file#nextseo-options). + + Or you can pass in a function to render your own meta tags. Note that you do **must** use [NextSeo](https://github.com/garmeeh/next-seo) when using this method. + + Read more about how to use this on [this page](../../guides/config/seo.mdx). + + + A repository identifier, if specified a GitHub widget with the star count and fork count is displayed on the right side of the header. + + The identifier needs to be either `{ORG_NAME}/{REPO_NAME}` or `{USER_NAME}/{REPO_NAME}`. For example: `mrjvs/neatojs`. + + + A text based logo to show top left of the header. If not specified, a placeholder is shown. + + You can also overwrite the logo, for example to show an image. Read more [about overwriting the logo](../../guides/config/theming.mdx#changing-the-logo). + + + + Text to display in the logo. + + + Link to make the logo redirect to when clicked. If not specified, the logo is not clickable. + + + + + The default layout to show for all pages associated with this site. Defaults to the layout with the ID `default`. + + + List of layouts to add to the site. Pages and directories can specify which layout they want to use. + + The default included layouts are still added even if you add items to this list. You can change the default layouts by making a layout yourself with the same ID as the defaults. + + Read more about layouts in [this guide](../../guides/advanced/customizing-layout.mdx#using-layouts). + + + + The ID of the layout + + + The layout settings for this layout, read more [about layout settings](./settings.mdx). + + + + + The layout settings for this site, read more [about layout settings](./settings.mdx). + + The settings in this settings layer act as defaults for following layers. The settings are overriden by the layout settings and directory settings in that order if they exist. + + + List of directories for this site, read more [about directories here](./directory.mdx). + + To have a sidebar, you will need at least one directory. + + + Options for the content footer (the footer placed right below the content). + + The visibility of the content footer is not controlled by the settings. To control the visibility of the footer, check [the footer page](../../guides/advanced/footer.mdx) for more info. + + + + Text shown in the content footer, by default it will be a copyright notice. + + + List of social media links shown in the content footer. Check [the social() page](./social.mdx) for usage. + + + Base URL of your Git repository, it will be used to show a "Edit on GitHub" link. Leave undefined if you don't want such a link. + + Check [this page](../../guides/advanced/footer.mdx#configuring-the-content-footer) for information on how to configure it. + + + + + Options for the page footer (the footer placed at the very bottom of the page). + + The visibility of the page footer is not controlled by the settings. To control the visibility of the footer, check [the footer page](../../guides/advanced/footer.mdx) for more info. + + + + Text shown in the page footer, it will be blank by default. + + + + + diff --git a/apps/docs/pages/docs/guider/api-reference/theme/social.mdx b/apps/docs/pages/docs/guider/api-reference/theme/social.mdx new file mode 100644 index 00000000..a122e958 --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/theme/social.mdx @@ -0,0 +1,58 @@ +# `social()` + +Social links, currently only usable in the content footer. + + +## Example + +```tsx title="theme.config.tsx" +export default defineTheme({ + contentFooter: { + socials: [ + social.twitter("https://x.com"), // Twitter and X both show the X logo + social.x("https://x.com"), + social.discord("https://discord.gg"), + social.github("https://github.com"), + social.slack("https://slack.com"), + social.mastodon("https://joinmastodon.org/"), + ], + }, +}) +``` + + +## Reference + +```tsx +function social.twitter(link); // Twitter and X both show the X logo +function social.x(link); +function social.discord(link); +function social.github(link); +function social.slack(link); +function social.mastodon(link); +``` + + + The link of the social media account. + + + +## Reference - Options + +```tsx +function social(options); +``` + + + The options for this group. + + + + The type of the social media. Can be any of these: `slack`, `mastodon`, `twitter`, `discord`, `github`. + + + + The link of the social media account. + + + diff --git a/apps/docs/pages/docs/guider/guides/config/examples.mdx b/apps/docs/pages/docs/guider/guides/config/examples.mdx deleted file mode 100644 index 8350ed3b..00000000 --- a/apps/docs/pages/docs/guider/guides/config/examples.mdx +++ /dev/null @@ -1,9 +0,0 @@ -# Examples - -Checking out examples can often be a fast shortcut on how to figure out the details of a frameworks. - -Below is a list of popular documentation sites, remade in Guider: - - -This article is a stub, please help by contributing to the docs. (I haven't made any examples yet) - diff --git a/apps/docs/pages/docs/guider/guides/config/landing.mdx b/apps/docs/pages/docs/guider/guides/config/landing.mdx index 07ff5080..fc7a527b 100644 --- a/apps/docs/pages/docs/guider/guides/config/landing.mdx +++ b/apps/docs/pages/docs/guider/guides/config/landing.mdx @@ -53,7 +53,7 @@ export default function LandingPage() { diff --git a/apps/docs/pages/docs/guider/guides/config/navigation.mdx b/apps/docs/pages/docs/guider/guides/config/navigation.mdx index fd494d9c..7fb9e926 100644 --- a/apps/docs/pages/docs/guider/guides/config/navigation.mdx +++ b/apps/docs/pages/docs/guider/guides/config/navigation.mdx @@ -12,11 +12,11 @@ You can use the following components, all of which are imported from `@neato/gui - `link(){:ts}`: A standard sidebar link with optional icon. - `link.nested(){:ts}`: A nested link, it's collapsable by the user. - `group(){:ts}`: A group or section, used for visual hierarchy. -- `seperator(){:ts}`: A plain & simple line. +- `separator(){:ts}`: A plain & simple line. - `component(){:ts}`: A custom component, you can render any React component in here. - Groups can contain any other components except another group. Nested links can only contain normal links and seperators. + Groups can contain any other components except another group. Nested links can only contain normal links and separators. Here is an example that uses every component. This sidebar configuration will @@ -40,7 +40,7 @@ sidebar: [ group("Group A", [ link("Link E", "/link/e"), ]) - seperator(), + separator(), component(() =>

Custom component

), ] ``` @@ -52,7 +52,7 @@ Adding links to the navigation bar is quite easy. You can use the following components, all of which are imported from `@neato/guider/theme`. - `link(){:ts}`: A standard link with optional icon. -- `seperator(){:ts}`: A plain & simple line. +- `separator(){:ts}`: A plain & simple line. You can configure the top navigation per site. Here is an example that uses every component: @@ -61,7 +61,7 @@ site("my-site", { navigation: [ link("Link A", "/link/a"), link("Link B with icon", "/link/b", { icon: 'fa6-solid:b' }), - seperator(), + separator(), link("Link C", "/link/c"), ] }) diff --git a/apps/docs/pages/docs/guider/guides/config/theming.mdx b/apps/docs/pages/docs/guider/guides/config/theming.mdx index 3ed4b3ec..dee0ea1a 100644 --- a/apps/docs/pages/docs/guider/guides/config/theming.mdx +++ b/apps/docs/pages/docs/guider/guides/config/theming.mdx @@ -123,11 +123,14 @@ settings: { There are currently no other options other than `flare` and just having it disabled. - ## Want to build a theme? Give the color wheel a spin and generate a theme for your documentation. If you want more freedom, you can also use this as a base for you main theme and just customize where neccesary. + + ```json + CODE + ``` diff --git a/apps/docs/pages/docs/guider/guides/deploy/cloudflare.mdx b/apps/docs/pages/docs/guider/guides/deploy/cloudflare.mdx index c77061d7..5e59e80b 100644 --- a/apps/docs/pages/docs/guider/guides/deploy/cloudflare.mdx +++ b/apps/docs/pages/docs/guider/guides/deploy/cloudflare.mdx @@ -1,5 +1,42 @@ # Cloudflare Pages - -This article is a stub, please help by contributing to the docs. - +A guide to deploy a Guider project to Cloudflare Pages. + + +## The guide + +Follow the steps below to deploy a Guider project to Cloudflare Pages. + + + + ### Make a new Application + + Go to [the cloudflare dashboard](https://dash.cloudflare.com) on under "Workers & Pages" click "Create application". + + + ### Select your repository + + On the "Create application" page, select the "Pages" tab. + + Choose a repository by pressing "Connect to Git" and then selecting it from the repository list. + + + ### Configure your project + + Configure the following fields: + - **Project name:** Choose a fitting name. + - **Production branch:** Select your release branch. + - **Framework preset:** Select "Next.js (Static HTML Export)" + - **Build command:** Set to `npm run build` (or your favourite package manager) + - **Root directory (advanced):** If you have your project in a subdirectory, set it here. otherwise leave empty. + + + ### Deploy + + Click the `Save and Deploy` button and wait until your site has been deployed. + + + Cloudflare has linked this deploy with your branch, meaning that once new changes are pushed. Cloudflare will automatically update your site. + + + diff --git a/apps/docs/pages/docs/guider/guides/deploy/github-pages.mdx b/apps/docs/pages/docs/guider/guides/deploy/github-pages.mdx index bbeebd1e..8d11e3f2 100644 --- a/apps/docs/pages/docs/guider/guides/deploy/github-pages.mdx +++ b/apps/docs/pages/docs/guider/guides/deploy/github-pages.mdx @@ -64,3 +64,7 @@ jobs: id: deployment uses: actions/deploy-pages@v4 ``` + + + This GitHub Action is activated on push of your release branch, meaning that once new changes are pushed. The action will automatically update your site. + diff --git a/apps/docs/pages/docs/guider/guides/deploy/netlify.mdx b/apps/docs/pages/docs/guider/guides/deploy/netlify.mdx index 11e9835e..c77cb980 100644 --- a/apps/docs/pages/docs/guider/guides/deploy/netlify.mdx +++ b/apps/docs/pages/docs/guider/guides/deploy/netlify.mdx @@ -1,5 +1,35 @@ -# Netlify +# Vercel - -This article is a stub, please help by contributing to the docs. - +A guide to deploy a Guider project to Netlify. + + +## The guide + +Follow the steps below to deploy a Guider project to Netlify. + + + + ### Make a new Netlify project + + Go to [New site](https://app.netlify.com/start) on Netlify, and select your repository. + + + ### Configure your project + + Configure the following fields: + - **Site name:** Choose a fitting name. + - **Site to deploy:** Set to `Other (configure manually)`. + - **Base directory:** Set to the project directory, set to `/` if unsure. + - **Build command:** Set to `npm run build` (or your favourite package manager). + - **Publish directory:** Set to `/out` (prefix it with your project directory if it's not root). + + + ### Deploy + + Click the `deploy` button and wait until your site has been deployed. + + + Netlify has linked this deploy with your branch, meaning that once new changes are pushed. Netlify will automatically update your site. + + + diff --git a/apps/docs/pages/docs/guider/guides/deploy/vercel.mdx b/apps/docs/pages/docs/guider/guides/deploy/vercel.mdx index 1cacc42b..0bd9b40b 100644 --- a/apps/docs/pages/docs/guider/guides/deploy/vercel.mdx +++ b/apps/docs/pages/docs/guider/guides/deploy/vercel.mdx @@ -1,5 +1,33 @@ # Vercel - -This article is a stub, please help by contributing to the docs. - +A guide to deploy a Guider project to Vercel. + + +## The guide + +Follow the steps below to deploy a Guider project on Vercel. + + + + ### Make a new Vercel project + + Go to [New project](https://vercel.com/new) on Vercel, and select your repository. + + + ### Configure your project + + Configure the following fields: + - **Project Name:** Choose a fitting name. + - **Framework Preset:** Set it to `Next.js`. + - **Root Directory:** Make sure it matches to the root of your Guider project. + + + ### Deploy + + Click the `deploy` button and wait until your site has been deployed. + + + Vercel has linked this deploy with your branch, meaning that once new changes are pushed. Vercel will automatically update your site. + + + diff --git a/apps/docs/pages/docs/guider/guides/getting-started/migration/from-docus.mdx b/apps/docs/pages/docs/guider/guides/getting-started/migration/from-docus.mdx index 6a1cf8d0..68916054 100644 --- a/apps/docs/pages/docs/guider/guides/getting-started/migration/from-docus.mdx +++ b/apps/docs/pages/docs/guider/guides/getting-started/migration/from-docus.mdx @@ -1,5 +1,48 @@ # Migrating from Docus - -This article is a stub, please help by contributing to the docs. - +Migrating can be a long journey, this guide aims to create a clear set of steps to move to Guider. + + +## Compatability table + +| Feature | Docus | Guider | +|---|:---:|:---:| +| Markdown based pages | **βœ“** | **βœ“** | +| Search bar | **βœ“** | 𐄂 | +| Dark mode | **βœ“** | **βœ“** | +| Light mode | **βœ“** | 𐄂 | +| SEO & custom meta tags | **βœ“** | **βœ“** | +| Redirects | **βœ“** | **βœ“** | +| Layouts | **βœ“** | **βœ“** | +| Component: Alert | **βœ“** | **βœ“** (called callouts) | +| Component: Badge | **βœ“** | 𐄂 | +| Component: BlockHero | **βœ“** | **βœ“** (Looks different) | +| Component: ButtonLink | **βœ“** | **βœ“** (called Button) | +| Component: Callouts | **βœ“** | 𐄂 (despite similar name, not supported) | +| Component: Card | **βœ“** | **βœ“** (part of the landing page) | +| Component: CardGrid | **βœ“** | **βœ“** (part of the landing page) | +| Component: CodeGroup | **βœ“** | **βœ“** | +| Component: CodeBlock | **βœ“** | **βœ“** (called Frame) | +| Component: CopyButton | **βœ“** | 𐄂 | +| Component: Icon | **βœ“** | 𐄂 | +| Component: List | **βœ“** | 𐄂 | +| Component: Sandbox | **βœ“** | 𐄂 | +| Component: Terminal | **βœ“** | 𐄂 | +| Component: VideoPlayer | **βœ“** | 𐄂 | + + +## Migration steps + +1. **Make a guider project:** Make a new guider project by following [this guide](../installation.mdx). +2. **Copy your markdown files over:** Copy over all Markdown files into the pages directory of the new project. + - Remove the numbers prefixed on front of your files and folders. The order is now in the theme config. + - Replace the component directives with MDX React components. + - Update frontmatter to set the layout ID instead of modifying the layout settings directly. See [this page](../../advanced/customizing-layout.mdx). + - Replace title in the frontmatter to a link in the theme config. +3. **Migrate _dir.yml files:** dir files don't exist in Guider. Check these steps: + - title goes in a `group()` in the theme config. + - replace `navigation.redirect` with a `createRedirect()` in a index.tsx + - title template can be set globally, not a per directory basis. +4. **Migrate app.config.ts:** The settings in Guider go into the theme config, along with your sidebar contents. +5. **Migrate vue components to react:** Guider is based in react, so to have custom components work you will need to port them. +6. **Finished:** That should be everything to migrate to Guider, congratulations! diff --git a/apps/docs/pages/docs/guider/guides/getting-started/migration/from-mintlify.mdx b/apps/docs/pages/docs/guider/guides/getting-started/migration/from-mintlify.mdx index 60b816c8..d1bcbf0a 100644 --- a/apps/docs/pages/docs/guider/guides/getting-started/migration/from-mintlify.mdx +++ b/apps/docs/pages/docs/guider/guides/getting-started/migration/from-mintlify.mdx @@ -1,5 +1,34 @@ # Migrating from Mintlify - -This article is a stub, please help by contributing to the docs. - +Migrating can be a long journey, this guide aims to create a clear set of steps to move to Guider. + + +## Compatability table + +| Feature | Mintlify | Guider | +|---|:---:|:---:| +| MDX based pages | **βœ“** | **βœ“** | +| Custom CSS/JS | **βœ“** | **βœ“** | +| Search bar | **βœ“** | 𐄂 | +| Dark mode | **βœ“** | **βœ“** | +| Light mode | **βœ“** | 𐄂 | +| Banners | **βœ“** | 𐄂 | +| Versions | **βœ“** | **βœ“** (through dropdown) | +| Groups/Tabs | **βœ“** | **βœ“** | +| Redirects | **βœ“** | **βœ“** | +| SEO & custom meta tags | **βœ“** | **βœ“** | +| Sitemaps | **βœ“** | 𐄂 | +| Custom domain | **βœ“** | **βœ“** (you host it yourself) | +| API playground / openAPI | **βœ“** | 𐄂 | +| Snippets | **βœ“** | 𐄂 (use custom components instead) | +| integrations | **βœ“** | 𐄂 (you can use NextJS libraries) | + + +## Migration steps + +1. **Make a guider project:** Make a new guider project by following [this guide](../installation.mdx). +2. **Copy your MDX files over:** Copy over all MDX files into the pages directory of the new project. +3. **Remove or replace unsupported components:** Not all components are supported by Guider. Check the compatibility table above. +4. **Migrate `mint.json` file:** In Mintlify, the json file is used for all configuration. In Guider this is done in the theme config. [Check out this guide](../../config/navigation.mdx). +5. **Update frontmatter:** Mintlify has some configuration in the frontmatter. Remove the unsupported properties or move them to the theme config. +6. **Finished:** That should be everything to migrate to Guider, congratulations! diff --git a/apps/docs/pages/docs/guider/guides/getting-started/migration/from-nextra.mdx b/apps/docs/pages/docs/guider/guides/getting-started/migration/from-nextra.mdx index 13c1c359..5c56f438 100644 --- a/apps/docs/pages/docs/guider/guides/getting-started/migration/from-nextra.mdx +++ b/apps/docs/pages/docs/guider/guides/getting-started/migration/from-nextra.mdx @@ -1,5 +1,37 @@ # Migrating from Nextra - -This article is a stub, please help by contributing to the docs. - +Migrating can be a long journey, this guide aims to create a clear set of steps to move to Guider. + + +## Compatability table + +| Feature | Nextra | Guider | +|---|:---:|:---:| +| MDX based pages | **βœ“** | **βœ“** | +| I18N support | **βœ“** | 𐄂 | +| Search bar | **βœ“** | 𐄂 | +| Dark mode | **βœ“** | **βœ“** | +| Light mode | **βœ“** | 𐄂 | +| Banners | **βœ“** | 𐄂 | +| SEO & custom meta tags | **βœ“** | **βœ“** | +| Customizable layouts | **βœ“** | **βœ“** | +| Custom navigation links | **βœ“** | **βœ“** | +| Component: Callout | **βœ“** | **βœ“** | +| Component: Tabs | **βœ“** | **βœ“** | +| Component: Cards | **βœ“** | 𐄂 | +| Component: Steps | **βœ“** | **βœ“** | +| Component: FileTree | **βœ“** | 𐄂 | +| Component: Bleed | **βœ“** | 𐄂 | +| Npm2Yarn integration | **βœ“** | **βœ“** | +| Edit on GitHub link | **βœ“** | **βœ“** | +| Collapsable sidebar | **βœ“** | 𐄂 | + + +## Migration steps + +1. **Make a guider project:** Make a new guider project by following [this guide](../installation.mdx). +2. **Copy your MDX files over:** Copy over all MDX files into the pages directory of the new project. +3. **Remove or replace unsupported components:** Not all components are supported by Guider. Check the compatibility table above. +4. **Migrate `_meta.json` files:** In Nextra, meta files are for storing navigation structures. In Guider this is done in the theme config. [Check out this guide](../../config/navigation.mdx). +5. **Migrate the theme config:** Many Nextra theme configuration options are also possible in Guider. Check out the compatibility table above. +6. **Finished:** That should be everything to migrate to Guider, congratulations! diff --git a/apps/docs/pages/docs/guider/index.tsx b/apps/docs/pages/docs/guider/index.tsx index 4db786d4..2a2b8bad 100644 --- a/apps/docs/pages/docs/guider/index.tsx +++ b/apps/docs/pages/docs/guider/index.tsx @@ -21,7 +21,7 @@ export default function LandingPage() { diff --git a/apps/docs/pages/docs/guider/writing/components/callouts.mdx b/apps/docs/pages/docs/guider/writing/components/callouts.mdx index 85767ece..e9afa689 100644 --- a/apps/docs/pages/docs/guider/writing/components/callouts.mdx +++ b/apps/docs/pages/docs/guider/writing/components/callouts.mdx @@ -61,3 +61,15 @@ In case you need to dynamically change the type of the callout, you can use the ```jsx I am a callout ``` + + +## Component API - `` + +The general component API, the more specific versions don't have any props. + + + The type and style of the callout, can be any of the following: `warning`, `note`, `important`, `caution`, `tip` + + + The contents of the callout, you can use markdown freely in here. + diff --git a/apps/docs/pages/docs/guider/writing/components/code-groups.mdx b/apps/docs/pages/docs/guider/writing/components/code-groups.mdx index cfb08cf9..3325bf72 100644 --- a/apps/docs/pages/docs/guider/writing/components/code-groups.mdx +++ b/apps/docs/pages/docs/guider/writing/components/code-groups.mdx @@ -78,3 +78,24 @@ Codegroup children can also contain `` components. See the example below. + + +## Component API - `` + +The base component, has no props other than children + + + The items of the CodeGroup. + + + +## Component API - `` + +The CodeGroup item, can only be a child of a `{:tsx}`. + + + The title of this CodeGroup item, will be displayed as the tab name. + + + The contents of this CodeGroup item. Must be a codeblock or a `{:tsx}` + diff --git a/apps/docs/pages/docs/guider/writing/components/fields.mdx b/apps/docs/pages/docs/guider/writing/components/fields.mdx index 35488001..12c4c398 100644 --- a/apps/docs/pages/docs/guider/writing/components/fields.mdx +++ b/apps/docs/pages/docs/guider/writing/components/fields.mdx @@ -47,8 +47,7 @@ You can also use the `{:tsx}` component to group properties A field with a type display, great for documenting types or structures. - + The title of the field diff --git a/apps/docs/pages/docs/guider/writing/components/frames.mdx b/apps/docs/pages/docs/guider/writing/components/frames.mdx index 6f2be991..7d7aabd7 100644 --- a/apps/docs/pages/docs/guider/writing/components/frames.mdx +++ b/apps/docs/pages/docs/guider/writing/components/frames.mdx @@ -35,3 +35,15 @@ If you don't want something to be centered. You can wrap your content in `
Hello world
+ + +## Component API - `` + +The Frame component. + + + Boolean property on the style of the frame. Set to `true` to remove the background grid. + + + The content of the frame. + diff --git a/apps/docs/pages/docs/guider/writing/components/steps.mdx b/apps/docs/pages/docs/guider/writing/components/steps.mdx index e37309ff..c5586432 100644 --- a/apps/docs/pages/docs/guider/writing/components/steps.mdx +++ b/apps/docs/pages/docs/guider/writing/components/steps.mdx @@ -32,3 +32,21 @@ You can put any content inside of a step, so don't feel restricted to just text. Step content goes here + + +## Component API - `` + +The base Steps component only has some children, no specific props. + + + The individual steps that should be displayed. + + + +## Component API - `` + +An individual step component only has some children, no specific props. + + + The contents of the Step. + diff --git a/apps/docs/pages/docs/guider/writing/components/tabs.mdx b/apps/docs/pages/docs/guider/writing/components/tabs.mdx index 5b9a6b6a..13ae36e8 100644 --- a/apps/docs/pages/docs/guider/writing/components/tabs.mdx +++ b/apps/docs/pages/docs/guider/writing/components/tabs.mdx @@ -86,3 +86,27 @@ If you would like the user's choice to be stored, you can give a `storageKey` pr Tab C + + +## Component API - `` + +The Tabs component + + + The tab items, must have the same number of items as there are tabs. + + + The storage key, to store the preferences against. See [this section](#storing-the-tab-choice) for usage. + + + The tabs to display. + + + +## Component API - `` + +A Tabs item can only be a child of a `{:tsx}`. + + + The contents of this Tab. + diff --git a/apps/docs/pages/index.tsx b/apps/docs/pages/index.tsx index cbfb560a..7bb44afb 100644 --- a/apps/docs/pages/index.tsx +++ b/apps/docs/pages/index.tsx @@ -38,7 +38,7 @@ export default function LandingPage() { {projects.map((v) => ( diff --git a/apps/docs/pages/showcase.tsx b/apps/docs/pages/showcase.tsx index 5573feb3..cb1ffe94 100644 --- a/apps/docs/pages/showcase.tsx +++ b/apps/docs/pages/showcase.tsx @@ -3,27 +3,22 @@ import { useMemo, useState } from 'react'; import { Showcase } from 'components/showcase-layout'; import type { ShowcaseTag, ShowcaseType } from 'components/showcase-card'; import { ShowcaseCard, ShowcaseCardContainer } from 'components/showcase-card'; +import pretendoImg from 'public/showcases/pretendo.png'; +import mwAccountImg from 'public/showcases/movie-web-account.png'; const showcases: ShowcaseType[] = [ { title: 'Pretendo', description: 'Uses Guider for protocol documentation.', href: 'https://developer.pretendo.network/', - imageUrl: 'https://placehold.co/600x400', - tags: ['guider'], - }, - { - title: 'movie-web docs', - description: 'Uses Guider for self-hosting documentation.', - href: 'https://movie-web.github.io/docs/', - imageUrl: 'https://placehold.co/600x400', + imageUrl: pretendoImg.src, tags: ['guider'], }, { title: 'movie-web account', description: 'Uses Config for their account service.', - href: 'https://github.com/movie-web/movie-web/', - imageUrl: 'https://placehold.co/600x400', + href: 'https://github.com/movie-web/backend/', + imageUrl: mwAccountImg.src, tags: ['config'], }, ]; @@ -40,11 +35,11 @@ export default function ShowcasePage() { Showcase - NeatoJS can make your life easier β€” it has for them! + NeatoJS increases your development speed β€” it has for them! Below you can find out who uses NeatoJS, inspire yourself and figure - out how we can best be of service. + out how NeatoJS can work best for you! {filtered.map((v) => ( diff --git a/apps/docs/public/showcases/movie-web-account.png b/apps/docs/public/showcases/movie-web-account.png new file mode 100644 index 00000000..e5bca90d Binary files /dev/null and b/apps/docs/public/showcases/movie-web-account.png differ diff --git a/apps/docs/public/showcases/pretendo.png b/apps/docs/public/showcases/pretendo.png new file mode 100644 index 00000000..0b6051fe Binary files /dev/null and b/apps/docs/public/showcases/pretendo.png differ diff --git a/apps/docs/theme.config.tsx b/apps/docs/theme.config.tsx index 41bd264b..c458016f 100644 --- a/apps/docs/theme.config.tsx +++ b/apps/docs/theme.config.tsx @@ -7,18 +7,13 @@ import { siteTemplate, social, type SiteComponent, - seperator, } from '@neato/guider/theme'; import { Logo } from 'components/logo'; const template = siteTemplate({ github: 'mrjvs/neatojs', dropdown: [link('Guider', '/docs/guider'), link('Config', '/docs/config')], - navigation: [ - link('Showcase', '/showcase'), - link('Showcase', '/showcase'), - seperator(), - ], + navigation: [link('Showcase', '/showcase')], settings: { colors: { primary: '#A880FF', @@ -128,7 +123,6 @@ export default defineTheme([ link('API reference + docs', gdGuides('/config/common/api-ref')), link('Blog posts + docs', gdGuides('/config/common/blog')), ]), - link('Examples', gdGuides('/config/examples')), ]), group('Advanced', [ link('Running multiple sites', gdGuides('/advanced/multi-site')), @@ -213,11 +207,14 @@ export default defineTheme([ group('Theme configuration', [ link('defineTheme()', gdApi('/theme/define-theme')), link('site()', gdApi('/theme/site')), + link('siteTemplate()', gdApi('/theme/site-template')), link('directory()', gdApi('/theme/directory')), link('link()', gdApi('/theme/link')), link('group()', gdApi('/theme/group')), - link('seperator()', gdApi('/theme/seperator')), + link('separator()', gdApi('/theme/separator')), link('component()', gdApi('/theme/component')), + link('social()', gdApi('/theme/social')), + link('Layout settings', gdApi('/theme/settings')), ]), group('_meta.json', [ @@ -239,6 +236,15 @@ export default defineTheme([ link('', gdApi('/components/guider-layout')), link('', gdApi('/components/guider-sidebar')), link('', gdApi('/components/guider-toc')), + link('', gdApi('/components/guider-logo')), + link( + '', + gdApi('/components/guider-content-footer'), + ), + link( + '', + gdApi('/components/guider-page-footer'), + ), ]), ], }), diff --git a/examples/guider/kitchen-sink/theme.config.tsx b/examples/guider/kitchen-sink/theme.config.tsx index 96c9e1a9..915c3180 100644 --- a/examples/guider/kitchen-sink/theme.config.tsx +++ b/examples/guider/kitchen-sink/theme.config.tsx @@ -4,7 +4,7 @@ import { directory, group, link, - seperator, + separator, site, type SiteComponent, } from '@neato/guider/theme'; @@ -19,7 +19,7 @@ const siteTemplate = site('docs', { link('API reference', '/api-ref'), link('Documentation', '/docs/guides', { icon: 'fa6-solid:house' }), link('API reference', '/api-ref'), - seperator(), + separator(), ], github: 'movie-web/movie-web', }); @@ -57,7 +57,7 @@ export default defineTheme([ link('Guides', '/docs/guides/'), link('How to?', '/docs/guides/how-to'), ]), - seperator(), + separator(), link.nested('Troubleshooting', '/docs/guides/troubleshooting', [ link('Guides', '/docs/guides/'), link('How to?', '/docs/guides/how-to'), diff --git a/packages/guider/README.md b/packages/guider/README.md index dc77e9f9..08da9fd3 100644 --- a/packages/guider/README.md +++ b/packages/guider/README.md @@ -13,7 +13,6 @@ Beautiful documentation sites, without all the hassle. Check out the documentati ## πŸ„Installation / usage -> [TIP] > **Visit the [documentation](https://neatojs.com/docs/guider/guides/installation) on how to install. diff --git a/packages/guider/package.json b/packages/guider/package.json index 0f8b822b..3633ddcd 100644 --- a/packages/guider/package.json +++ b/packages/guider/package.json @@ -1,6 +1,6 @@ { "name": "@neato/guider", - "version": "0.1.3", + "version": "0.1.4", "description": "Beautiful documentation sites, without all the hassle", "main": "./dist/index.js", "type": "module", diff --git a/packages/guider/src/client/components/public/card.tsx b/packages/guider/src/client/components/public/card.tsx index 0d8e4fc5..8d24bad8 100644 --- a/packages/guider/src/client/components/public/card.tsx +++ b/packages/guider/src/client/components/public/card.tsx @@ -23,7 +23,7 @@ export function Card(props: CardProps) { export function CardGrid(props: { children?: ReactNode }) { return ( -
+
{props.children}
); diff --git a/packages/guider/src/client/hooks/use-page-switch.ts b/packages/guider/src/client/hooks/use-page-switch.ts new file mode 100644 index 00000000..20eafbeb --- /dev/null +++ b/packages/guider/src/client/hooks/use-page-switch.ts @@ -0,0 +1,12 @@ +import { useRouter } from 'next/router'; +import { useCallback, useEffect } from 'react'; + +export function usePageSwitch(cb: () => void, deps: any[]) { + const router = useRouter(); + const func = useCallback(cb, deps); + useEffect(() => { + return () => { + func(); + }; + }, [router.pathname, func]); +} diff --git a/packages/guider/src/client/partials/content-footer/github-edit-link.tsx b/packages/guider/src/client/partials/content-footer/github-edit-link.tsx index aefabb72..18da9f9f 100644 --- a/packages/guider/src/client/partials/content-footer/github-edit-link.tsx +++ b/packages/guider/src/client/partials/content-footer/github-edit-link.tsx @@ -9,7 +9,7 @@ export function useEditLink(baseUrl: string | null | undefined): string | null { const parsed = gitUrlParse(baseUrl); let filePath = parsed.filepath; filePath += filePath.length > 0 ? '/' : ''; - filePath += file.filePath; + filePath += file.urlSafeFilePath; // Resets the filepath as we want to manually construct it parsed.filepath = ''; diff --git a/packages/guider/src/client/partials/header/dropdown.tsx b/packages/guider/src/client/partials/header/dropdown.tsx index 73801f5d..48a2dfc1 100644 --- a/packages/guider/src/client/partials/header/dropdown.tsx +++ b/packages/guider/src/client/partials/header/dropdown.tsx @@ -30,13 +30,19 @@ function DropdownItem(props: { link: LinkComponent; active?: boolean }) { function DropdownLink(props: { link: LinkComponent }) { return ( - - - {({ isActive }) => ( - - )} - - + {({ close }) => ( + + + {({ isActive }) => ( + + )} + + + )} ); } @@ -96,7 +102,7 @@ export function HeaderDropdown(props: { dropdown: DropdownChildren[] }) { })} > - {activeItem?.title ?? 'Select site...'} + {activeItem?.title ?? 'Select site'} diff --git a/packages/guider/src/client/partials/header/nav.tsx b/packages/guider/src/client/partials/header/nav.tsx index b536f048..164fd382 100644 --- a/packages/guider/src/client/partials/header/nav.tsx +++ b/packages/guider/src/client/partials/header/nav.tsx @@ -32,7 +32,7 @@ function NavCustomComponent(props: { component: CustomComponentComponent }) { return {props.component.component?.()}; } -function NavSeperator() { +function NavSeparator() { return (
); @@ -46,7 +46,7 @@ export function HeaderNav(props: { items: TopNavChildren[] }) { if (v.type === 'component') return ; if (v.type === 'link') return ; - if (v.type === 'seperator') return ; + if (v.type === 'separator') return ; return null; })} diff --git a/packages/guider/src/client/partials/header/sidebar-mobile-nav.tsx b/packages/guider/src/client/partials/header/sidebar-mobile-nav.tsx index 09902eaf..ef29014e 100644 --- a/packages/guider/src/client/partials/header/sidebar-mobile-nav.tsx +++ b/packages/guider/src/client/partials/header/sidebar-mobile-nav.tsx @@ -1,12 +1,13 @@ import classNames from 'classnames'; import { Fragment, useEffect, useState } from 'react'; import { makeKey } from 'src/client/utils/make-key'; +import { usePageSwitch } from 'src/client/hooks/use-page-switch'; import { GuiderSidebarContent } from '../sidebar'; import { Icon } from '../../components/icon'; import type { TabsChildren } from '../../../theme/components/site'; import type { CustomComponentComponent } from '../../../theme/components/component'; import { SidebarStarLink } from '../sidebar/star-link'; -import { SidebarSeperator } from '../sidebar/seperator'; +import { SidebarSeparator } from '../sidebar/separator'; function CustomComponentTab(props: { component: CustomComponentComponent }) { return {props.component.component?.()}; @@ -14,6 +15,9 @@ function CustomComponentTab(props: { component: CustomComponentComponent }) { export function SidebarMobileNav(props: { tabs: TabsChildren[] }) { const [navOpen, setNavOpen] = useState(false); + usePageSwitch(() => { + setNavOpen(false); + }, []); const toggleButton = (
diff --git a/packages/guider/src/client/partials/header/top-mobile-nav.tsx b/packages/guider/src/client/partials/header/top-mobile-nav.tsx index 82cae3fa..f0c4523b 100644 --- a/packages/guider/src/client/partials/header/top-mobile-nav.tsx +++ b/packages/guider/src/client/partials/header/top-mobile-nav.tsx @@ -1,5 +1,6 @@ import classNames from 'classnames'; import { useEffect, useState } from 'react'; +import { usePageSwitch } from 'src/client/hooks/use-page-switch'; import { Icon } from '../../components/icon'; import type { TopNavChildren } from '../../../theme'; import { GithubDisplay } from '../../components/github'; @@ -10,6 +11,9 @@ export function TopMobileNav(props: { github: { org?: string; repo?: string }; }) { const [navOpen, setNavOpen] = useState(false); + usePageSwitch(() => { + setNavOpen(false); + }, []); const toggleButton = (
diff --git a/packages/guider/src/client/partials/sidebar/seperator.tsx b/packages/guider/src/client/partials/sidebar/separator.tsx similarity index 68% rename from packages/guider/src/client/partials/sidebar/seperator.tsx rename to packages/guider/src/client/partials/sidebar/separator.tsx index 7cc2a38b..2d4ddf01 100644 --- a/packages/guider/src/client/partials/sidebar/seperator.tsx +++ b/packages/guider/src/client/partials/sidebar/separator.tsx @@ -1,3 +1,3 @@ -export function SidebarSeperator() { +export function SidebarSeparator() { return
; } diff --git a/packages/guider/src/client/partials/sidebar/sidebar.tsx b/packages/guider/src/client/partials/sidebar/sidebar.tsx index cf01d9a1..74e797e3 100644 --- a/packages/guider/src/client/partials/sidebar/sidebar.tsx +++ b/packages/guider/src/client/partials/sidebar/sidebar.tsx @@ -4,7 +4,7 @@ import { useGuider } from '../../hooks/use-guider'; import { GuiderLayoutContext } from '../../page/context'; import { SidebarLink } from './link'; import { SidebarCustomComponent } from './component'; -import { SidebarSeperator } from './seperator'; +import { SidebarSeparator } from './separator'; import { SidebarGroup } from './group'; import { SidebarNested } from './nested'; import { SidebarStarLink } from './star-link'; @@ -26,7 +26,7 @@ export function SidebarInternal() { return ; if (link.type === 'component') return ; - if (link.type === 'seperator') return ; + if (link.type === 'separator') return ; if (link.type === 'group') return ; return null; diff --git a/packages/guider/src/client/utils/make-key.ts b/packages/guider/src/client/utils/make-key.ts index cd481203..df3e7de9 100644 --- a/packages/guider/src/client/utils/make-key.ts +++ b/packages/guider/src/client/utils/make-key.ts @@ -1,7 +1,7 @@ import type { LinkComponent, NestableLinkComponent, - SeperatorComponent, + SeparatorComponent, GroupComponent, CustomComponentComponent, } from 'src/theme'; @@ -9,7 +9,7 @@ import type { export type KeyableComponets = | LinkComponent | NestableLinkComponent - | SeperatorComponent + | SeparatorComponent | CustomComponentComponent | GroupComponent; diff --git a/packages/guider/src/styles/components/lists.css b/packages/guider/src/styles/components/lists.css index aa9051d9..cf832ac2 100644 --- a/packages/guider/src/styles/components/lists.css +++ b/packages/guider/src/styles/components/lists.css @@ -24,11 +24,11 @@ /* * numbered lists */ -ol.neato-guider-list > li .neato-guider-list-line { +ol.neato-guider-list > li > .neato-guider-list-line { @apply gd-bg-transparent gd-mt-0 gd-text-text; } -ol.neato-guider-list > li .neato-guider-list-line::before { +ol.neato-guider-list > li > .neato-guider-list-line::before { counter-increment: listitem; content: counter(listitem) "."; } diff --git a/packages/guider/src/styles/global.css b/packages/guider/src/styles/global.css index 9acb25e0..852ede6c 100644 --- a/packages/guider/src/styles/global.css +++ b/packages/guider/src/styles/global.css @@ -21,6 +21,11 @@ body[data-stop-overflow="true"] { scrollbar-gutter: stable; } +body[data-mobile-stop-overflow="true"] { + @apply gd-overflow-hidden md:gd-overflow-auto; + scrollbar-gutter: stable; +} + ::-webkit-scrollbar-track { background-color: transparent; } diff --git a/packages/guider/src/theme/components/directory.ts b/packages/guider/src/theme/components/directory.ts index c4763240..b210f611 100644 --- a/packages/guider/src/theme/components/directory.ts +++ b/packages/guider/src/theme/components/directory.ts @@ -1,6 +1,6 @@ import type { PartialDeep } from 'type-fest'; import type { LinkComponent, NestableLinkComponent } from './link'; -import type { SeperatorComponent } from './seperator'; +import type { SeparatorComponent } from './separator'; import type { CustomComponentComponent } from './component'; import type { GroupComponent, GroupComponentChildren } from './group'; import type { LayoutSettings } from './settings'; @@ -9,7 +9,7 @@ import { makeLayoutSettings } from './layout'; type DirectoryComponentChildren = | NestableLinkComponent | LinkComponent - | SeperatorComponent + | SeparatorComponent | CustomComponentComponent | GroupComponent; diff --git a/packages/guider/src/theme/components/group.ts b/packages/guider/src/theme/components/group.ts index dbfaf896..1ba6e986 100644 --- a/packages/guider/src/theme/components/group.ts +++ b/packages/guider/src/theme/components/group.ts @@ -1,11 +1,11 @@ import type { CustomComponentComponent } from './component'; import type { LinkComponent, NestableLinkComponent } from './link'; -import type { SeperatorComponent } from './seperator'; +import type { SeparatorComponent } from './separator'; export type GroupComponentChildren = | NestableLinkComponent | LinkComponent - | SeperatorComponent + | SeparatorComponent | CustomComponentComponent; export interface GroupOptions { diff --git a/packages/guider/src/theme/components/index.ts b/packages/guider/src/theme/components/index.ts index bebab9d1..9550859c 100644 --- a/packages/guider/src/theme/components/index.ts +++ b/packages/guider/src/theme/components/index.ts @@ -2,7 +2,7 @@ export * from './component'; export * from './directory'; export * from './group'; export * from './link'; -export * from './seperator'; +export * from './separator'; export * from './site'; export * from './footer'; export * from './layout'; diff --git a/packages/guider/src/theme/components/link.ts b/packages/guider/src/theme/components/link.ts index e97e0110..d9ec1bbb 100644 --- a/packages/guider/src/theme/components/link.ts +++ b/packages/guider/src/theme/components/link.ts @@ -1,6 +1,6 @@ -import type { SeperatorComponent } from './seperator'; +import type { SeparatorComponent } from './separator'; -export type NestedLinkComponentChildren = LinkComponent | SeperatorComponent; +export type NestedLinkComponentChildren = LinkComponent | SeparatorComponent; export interface ExtraLinkOptions { icon?: string; diff --git a/packages/guider/src/theme/components/separator.ts b/packages/guider/src/theme/components/separator.ts new file mode 100644 index 00000000..37f84e2e --- /dev/null +++ b/packages/guider/src/theme/components/separator.ts @@ -0,0 +1,11 @@ +export interface SeparatorComponent { + type: 'separator'; +} + +export type SeparatorBuilder = () => SeparatorComponent; + +export const separator: SeparatorBuilder = () => { + return { + type: 'separator', + }; +}; diff --git a/packages/guider/src/theme/components/seperator.ts b/packages/guider/src/theme/components/seperator.ts deleted file mode 100644 index 96c2c523..00000000 --- a/packages/guider/src/theme/components/seperator.ts +++ /dev/null @@ -1,11 +0,0 @@ -export interface SeperatorComponent { - type: 'seperator'; -} - -export type SeperatorBuilder = () => SeperatorComponent; - -export const seperator: SeperatorBuilder = () => { - return { - type: 'seperator', - }; -}; diff --git a/packages/guider/src/theme/components/site.ts b/packages/guider/src/theme/components/site.ts index a3263a77..becc6d09 100644 --- a/packages/guider/src/theme/components/site.ts +++ b/packages/guider/src/theme/components/site.ts @@ -4,7 +4,7 @@ import type { NextSeoProps } from 'next-seo'; import type { DirectoryComponent } from './directory'; import type { LinkComponent } from './link'; import type { CustomComponentComponent } from './component'; -import type { SeperatorComponent } from './seperator'; +import type { SeparatorComponent } from './separator'; import type { LayoutSettings, PopulatedLayoutSettings } from './settings'; import { makeLayoutSettings, @@ -24,7 +24,7 @@ import type { GroupComponent } from './group'; export type TopNavChildren = | LinkComponent - | SeperatorComponent + | SeparatorComponent | CustomComponentComponent; export type TabsChildren = LinkComponent | CustomComponentComponent; diff --git a/packages/guider/src/theme/types.ts b/packages/guider/src/theme/types.ts index 48cf5fe3..b97b42ec 100644 --- a/packages/guider/src/theme/types.ts +++ b/packages/guider/src/theme/types.ts @@ -17,4 +17,5 @@ export type MetaMapItem = { export type PageMapItem = { sitePath: string; filePath: string; + urlSafeFilePath: string; }; diff --git a/packages/guider/src/webpack/loader/md-loader.ts b/packages/guider/src/webpack/loader/md-loader.ts index 788a77da..82995566 100644 --- a/packages/guider/src/webpack/loader/md-loader.ts +++ b/packages/guider/src/webpack/loader/md-loader.ts @@ -1,4 +1,3 @@ -import { parse, format } from 'node:path'; import { compile } from '@mdx-js/mdx'; import remarkFrontmatter from 'remark-frontmatter'; import remarkHeadings from '@vcarl/remark-headings'; @@ -46,13 +45,24 @@ export async function mdLoader(source: string): Promise { const hasProtocol = Boolean(url.match(/[a-zA-Z]+:/g)); if (hasProtocol) return url; - // must be relative url const [path, hash] = url.split('#', 2); - const parsedPath = parse(path); - parsedPath.ext = ''; - parsedPath.base = ''; + + const pathSections = path.split('/'); + const lastSectionIndex = pathSections.length - 1; + + // We get the last section so that only the last extension is removed + // e.g. bar.ts.mdx -> bar.ts + const lastDot = pathSections[lastSectionIndex].lastIndexOf('.'); + + // If there is no dot, there is no extension to remove so we can return the url as is + if (lastDot === -1) return url; + + pathSections[lastSectionIndex] = pathSections[ + lastSectionIndex + ].slice(0, lastDot); + const hashPath = hash && hash.length > 0 ? `#${hash}` : ''; - return `${format(parsedPath)}${hashPath}`; + return `${pathSections.join('/')}${hashPath}`; }, }, ], diff --git a/packages/guider/src/webpack/plugin/collector.ts b/packages/guider/src/webpack/plugin/collector.ts index b417c5a9..4c1ed078 100644 --- a/packages/guider/src/webpack/plugin/collector.ts +++ b/packages/guider/src/webpack/plugin/collector.ts @@ -22,6 +22,7 @@ export type CollectorItem = { export type PageMapItem = { sitePath: string; filePath: string; // path relative to project root + urlSafeFilePath: string; // filePath with / as separator }; export interface MetaCollectorResult { @@ -29,12 +30,20 @@ export interface MetaCollectorResult { pageMap: PageMapItem[]; } +const pathSeparatorRegex = RegExp(`\\${sep}`, 'g'); +function normalizePathSeparator(path: string): string { + return path.replace(pathSeparatorRegex, '/'); +} + async function filePathToSitePath( filePath: string, ): Promise { - const strippedPath = dirname(relative('./pages', filePath)); + let strippedPath = dirname(relative('./pages', filePath)); const fileContents = await readFile(filePath, 'utf-8'); const parsedContents = JSON.parse(fileContents); + + strippedPath = normalizePathSeparator(strippedPath); + return { sitePath: `/${strippedPath}`, fileContents: parsedContents, @@ -49,12 +58,16 @@ async function pagePathToSitePath( let dir = dirname(relative('./pages', filePath)); if (dir === '.') dir = ''; + dir = normalizePathSeparator(dir); + const urlSafeFilePath = normalizePathSeparator(filePath); + if (file.startsWith('_')) return null; const strippedPath = file === 'index' ? dir : `${dir}/${file}`; return { sitePath: strippedPath.startsWith('/') ? strippedPath : `/${strippedPath}`, filePath, + urlSafeFilePath, }; } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 7385f172..4b65a689 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -26,6 +26,9 @@ importers: classnames: specifier: ^2.5.1 version: 2.5.1 + color: + specifier: ^4.2.3 + version: 4.2.3 next: specifier: ^14.1.0 version: 14.1.0(react-dom@18.2.0)(react@18.2.0) @@ -45,6 +48,9 @@ importers: '@repo/typescript-config': specifier: workspace:* version: link:../../packages/typescript-config + '@types/color': + specifier: ^3.0.6 + version: 3.0.6 '@types/react': specifier: 18.2.56 version: 18.2.56