diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 00000000..a0ce331a --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 NeatoJS + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/apps/docs/components/home-card.module.css b/apps/docs/components/home-card.module.css new file mode 100644 index 00000000..9d1c804b --- /dev/null +++ b/apps/docs/components/home-card.module.css @@ -0,0 +1,59 @@ +.container > * { + margin-bottom: 1rem; +} + +.container > *:last-child { + margin-bottom: 0; +} + +.card { + display: flex; + gap: .5rem; + border: 1px solid #0F2B33; + border-radius: 15px; + padding: 1.5rem; + transition: border-color 100ms ease-in-out; +} +.card:hover { + border-color: #1e4853; +} + +.body { + flex: 1; +} + +.right { + display: flex; + align-items: center; +} + +.title { + font-size: 1.25rem; + color: white; + margin-bottom: 0.5rem; + font-weight: bold; + display: inline-block; +} +.title:hover { + opacity: 0.75; +} + +.desc { + line-height: 1.3; + max-width: 320px; +} + +.icon { + font-size: 1.75rem; + margin-top: 0.2rem; + color: #50A0EA; +} + +@media screen and (max-width: 740px) { + .card { + flex-direction: column; + } + .right { + margin-top: 2rem; + } +} diff --git a/apps/docs/components/home-card.tsx b/apps/docs/components/home-card.tsx new file mode 100644 index 00000000..70339854 --- /dev/null +++ b/apps/docs/components/home-card.tsx @@ -0,0 +1,40 @@ +import type { ReactNode } from 'react'; +import { Icon } from '@neato/guider/client'; +import Link from 'next/link'; +import styles from './home-card.module.css'; + +function Card(props: { + children?: ReactNode; + right?: ReactNode; + icon: string; +}) { + return ( +
+ +
{props.children}
+
{props.right}
+
+ ); +} + +function Title(props: { children?: ReactNode; href: string }) { + return ( + +

{props.children}

+ + ); +} + +function Description(props: { children?: ReactNode }) { + return

{props.children}

; +} + +export function HomeCardContainer(props: { children?: ReactNode }) { + return
{props.children}
; +} + +export const HomeCard = { + Card, + Title, + Description, +}; diff --git a/apps/docs/components/home.module.css b/apps/docs/components/home.module.css new file mode 100644 index 00000000..d58cb8e2 --- /dev/null +++ b/apps/docs/components/home.module.css @@ -0,0 +1,19 @@ +.home { + max-width: 750px; + margin: 5rem auto; +} + +.title { + font-size: 2rem; + color: white; + margin-bottom: 1.5rem; + font-weight: bold; + max-width: 480px; +} + +.subtitle { + font-size: 1.125rem; + line-height: 1.3; + max-width: 480px; + margin-bottom: 4rem; +} diff --git a/apps/docs/components/home.tsx b/apps/docs/components/home.tsx new file mode 100644 index 00000000..64d2dd89 --- /dev/null +++ b/apps/docs/components/home.tsx @@ -0,0 +1,20 @@ +import type { ReactNode } from 'react'; +import styles from './home.module.css'; + +function Container(props: { children?: ReactNode }) { + return
{props.children}
; +} + +function Title(props: { children?: ReactNode }) { + return

{props.children}

; +} + +function Subtitle(props: { children?: ReactNode }) { + return

{props.children}

; +} + +export const Home = { + Container, + Title, + Subtitle, +}; diff --git a/apps/docs/components/logo.module.css b/apps/docs/components/logo.module.css new file mode 100644 index 00000000..9c58d217 --- /dev/null +++ b/apps/docs/components/logo.module.css @@ -0,0 +1,23 @@ +.logo img { + height: 2rem; + margin-right: .5rem; +} + +.logo { + font-weight: 700; + color: white; + display: flex; + align-items: center; + transition: background-color 100ms ease-in-out, transform 100ms ease-in-out; + border-radius: 5px; + padding: .5rem; + margin-left: -0.5rem; +} + +.logo:hover { + background-color: rgb(var(--colors-bgLightest)); +} + +.logo:active { + transform: scale(1.05); +} diff --git a/apps/docs/components/logo.tsx b/apps/docs/components/logo.tsx new file mode 100644 index 00000000..b237a735 --- /dev/null +++ b/apps/docs/components/logo.tsx @@ -0,0 +1,10 @@ +import Link from 'next/link'; +import styles from './logo.module.css'; + +export function Logo() { + return ( + + NeatoJS + + ); +} diff --git a/apps/docs/pages/_app.tsx b/apps/docs/pages/_app.tsx index 03463a97..b77d1e9d 100644 --- a/apps/docs/pages/_app.tsx +++ b/apps/docs/pages/_app.tsx @@ -1,6 +1,4 @@ -import type { AppProps } from 'next/app'; import '@neato/guider/style.css'; +import { createGuiderApp } from '@neato/guider/client'; -export default function MyApp({ Component, pageProps }: AppProps) { - return ; -} +export default createGuiderApp(); diff --git a/apps/docs/pages/_meta.json b/apps/docs/pages/_meta.json new file mode 100644 index 00000000..0d5117e3 --- /dev/null +++ b/apps/docs/pages/_meta.json @@ -0,0 +1,3 @@ +{ + "site": "main" +} diff --git a/apps/docs/pages/docs/config/index.tsx b/apps/docs/pages/docs/config/index.tsx index c2344cf5..0efcb602 100644 --- a/apps/docs/pages/docs/config/index.tsx +++ b/apps/docs/pages/docs/config/index.tsx @@ -1,3 +1,38 @@ -import { createRedirect } from '@neato/guider/client'; +import { + Button, + Card, + CardGrid, + GuiderLayout, + Hero, +} from '@neato/guider/client'; -export default createRedirect({ to: '/docs/config/guide/why-neat-config' }); +export default function LandingPage() { + return ( + + + Simple type-safe configuration + + Configure with json files or environment variables, without losing + type-safety + + + + + + + + + Effortlessly create beautiful documentation sites with just markdown. + + + Effortlessly create beautiful documentation sites with just markdown. + + + Effortlessly create beautiful documentation sites with just markdown. + + + + ); +} 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 new file mode 100644 index 00000000..6bdc3bbb --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/components/guider-header.mdx @@ -0,0 +1,5 @@ +# `` + + +This article is a stub, please help by contributing to the docs. + 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 new file mode 100644 index 00000000..80acf707 --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/components/guider-layout.mdx @@ -0,0 +1,5 @@ +# `` + + +This article is a stub, please help by contributing to the docs. + 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 new file mode 100644 index 00000000..0c77caaa --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/components/guider-sidebar.mdx @@ -0,0 +1,5 @@ +# `` + + +This article is a stub, please help by contributing to the docs. + 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 new file mode 100644 index 00000000..065bf973 --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/components/guider-toc.mdx @@ -0,0 +1,5 @@ +# `` + + +This article is a stub, please help by contributing to the docs. + 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 new file mode 100644 index 00000000..83f39fd5 --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/functions/create-not-found-page.mdx @@ -0,0 +1,5 @@ +# `createNotFoundPage()` + + +This article is a stub, please help by contributing to the docs. + 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 new file mode 100644 index 00000000..93a18b20 --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/functions/create-redirect.mdx @@ -0,0 +1,5 @@ +# `createRedirect()` + + +This article is a stub, please help by contributing to the docs. + 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 new file mode 100644 index 00000000..d48f0833 --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/functions/use-guider-page.mdx @@ -0,0 +1,5 @@ +# `useGuiderPage()` + + +This article is a stub, please help by contributing to the docs. + 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 new file mode 100644 index 00000000..0762a695 --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/functions/use-guider.mdx @@ -0,0 +1,5 @@ +# `useGuider()` + + +This article is a stub, please help by contributing to the docs. + diff --git a/apps/docs/pages/docs/guider/api-reference/index.mdx b/apps/docs/pages/docs/guider/api-reference/index.mdx deleted file mode 100644 index 599ca37a..00000000 --- a/apps/docs/pages/docs/guider/api-reference/index.mdx +++ /dev/null @@ -1,3 +0,0 @@ -# Welcome to Guider - -Nothing is here yet, check back later! diff --git a/apps/docs/pages/docs/guider/api-reference/index.tsx b/apps/docs/pages/docs/guider/api-reference/index.tsx new file mode 100644 index 00000000..ddd6ff30 --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/index.tsx @@ -0,0 +1,5 @@ +import { createRedirect } from '@neato/guider/client'; + +export default createRedirect({ + to: '/docs/guider/api-reference/theme/define-theme', +}); diff --git a/apps/docs/pages/docs/guider/api-reference/meta/structure.mdx b/apps/docs/pages/docs/guider/api-reference/meta/structure.mdx new file mode 100644 index 00000000..1b30aef3 --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/meta/structure.mdx @@ -0,0 +1,5 @@ +# Structure of `_meta.json` + + +This article is a stub, please help by contributing to the docs. + diff --git a/apps/docs/pages/docs/guider/api-reference/test.mdx b/apps/docs/pages/docs/guider/api-reference/test.mdx deleted file mode 100644 index 599ca37a..00000000 --- a/apps/docs/pages/docs/guider/api-reference/test.mdx +++ /dev/null @@ -1,3 +0,0 @@ -# Welcome to Guider - -Nothing is here yet, check back later! diff --git a/apps/docs/pages/docs/guider/api-reference/theme/component.mdx b/apps/docs/pages/docs/guider/api-reference/theme/component.mdx new file mode 100644 index 00000000..f6e46a66 --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/theme/component.mdx @@ -0,0 +1,5 @@ +# `component()` + + +This article is a stub, please help by contributing to the docs. + 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 new file mode 100644 index 00000000..1756f30a --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/theme/define-theme.mdx @@ -0,0 +1,5 @@ +# `defineTheme()` + + +This article is a stub, please help by contributing to the docs. + diff --git a/apps/docs/pages/docs/guider/api-reference/theme/directory.mdx b/apps/docs/pages/docs/guider/api-reference/theme/directory.mdx new file mode 100644 index 00000000..90bc7acf --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/theme/directory.mdx @@ -0,0 +1,5 @@ +# `directory()` + + +This article is a stub, please help by contributing to the docs. + diff --git a/apps/docs/pages/docs/guider/api-reference/theme/group.mdx b/apps/docs/pages/docs/guider/api-reference/theme/group.mdx new file mode 100644 index 00000000..adc1ce5a --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/theme/group.mdx @@ -0,0 +1,5 @@ +# `group()` + + +This article is a stub, please help by contributing to the docs. + diff --git a/apps/docs/pages/docs/guider/api-reference/theme/link.mdx b/apps/docs/pages/docs/guider/api-reference/theme/link.mdx new file mode 100644 index 00000000..800154da --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/theme/link.mdx @@ -0,0 +1,5 @@ +# `link()` + + +This article is a stub, please help by contributing to the docs. + diff --git a/apps/docs/pages/docs/guider/api-reference/theme/seperator.mdx b/apps/docs/pages/docs/guider/api-reference/theme/seperator.mdx new file mode 100644 index 00000000..3845f3b3 --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/theme/seperator.mdx @@ -0,0 +1,5 @@ +# `seperator()` + + +This article is a stub, please help by contributing to the docs. + diff --git a/apps/docs/pages/docs/guider/api-reference/theme/site.mdx b/apps/docs/pages/docs/guider/api-reference/theme/site.mdx new file mode 100644 index 00000000..4dc241c9 --- /dev/null +++ b/apps/docs/pages/docs/guider/api-reference/theme/site.mdx @@ -0,0 +1,5 @@ +# `site()` + + +This article is a stub, please help by contributing to the docs. + diff --git a/apps/docs/pages/docs/guider/guides/advanced/customizing-layout.mdx b/apps/docs/pages/docs/guider/guides/advanced/customizing-layout.mdx new file mode 100644 index 00000000..3e8a1d8b --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/advanced/customizing-layout.mdx @@ -0,0 +1,65 @@ +# Customising layout + +The flexibilty of Guider really shines with its overwritable partials. + + +## Partials + +Partials are sections of the interface, you can replace them and toggle them at will. +Here are all possibilities: + - `toc`: The table of contents section. + - `sidebar`: The sidebar navigation menu. + - `navigation`: The header navigation menu. + - `contentFooter`: The content footer, placed right below content. + - `pageFooter`: The page footer, placed at the very bottom of the page. Disabled by default. + - `logo`: The logo, shown in the navigation bar and page footer. + - `pageLayout`: The entire page, cannot be turned off. + + +## Turning partials on or off + +You can turn off any partial on or off at [any layout settings level](/docs/guider/guides/config/theming#introduction-to-layout-settings). +Simply set the partial to `true{:ts}` or `false{:ts}`. Here is an example with the sidebar: + +```tsx +settings: { + sidebar: false, +} +``` + +This will turn off the sidebar for that settings level. + + +## Overwriting the partial + +You can replace any partial with your own component at [any layout settings level](/docs/guider/guides/config/theming#introduction-to-layout-settings). +Just set the partial to your component function - this will also enable it at the same time. Here is an example that overwrites the logo: + +```tsx +settings: { + logo: () =>

My Company

, +} +``` + +If you are making a more complex partial that needs to display another partial, you can use the theme components (e.g. `{:tsx}`). +Find all of them in the API reference tab. + + +## Using layouts + +- Making layouts +- How to use them effectively + + +This section is a stub, please help by contributing to the docs. + + + +## The default layouts + +The default layouts will always be present. They can not be removed but they can be overwritten. Just add a layout with the same ID as the +default layout of your choice. These are the defaults: +- `default`: The default layout of every page +- `page`: Layout for simple pages without sidebar, TOC or content footer. +- `article`: Layout for articles, without a sidebar or content footer. +- `raw`: Layout for when you just want to make a raw page without any of the other layouts. diff --git a/apps/docs/pages/docs/guider/guides/advanced/deep-dive.mdx b/apps/docs/pages/docs/guider/guides/advanced/deep-dive.mdx new file mode 100644 index 00000000..7cd4a7aa --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/advanced/deep-dive.mdx @@ -0,0 +1,10 @@ +# Deep-dive concepts + +- What are sites, when to use multiple? +- What are directories, when to use them? +- What are layouts, when to use them? +- Ties between the theme and the pages (pages link to theme, theme doesnt link to pages). + + +This article is a stub, please help by contributing to the docs. + diff --git a/apps/docs/pages/docs/guider/guides/advanced/footer.mdx b/apps/docs/pages/docs/guider/guides/advanced/footer.mdx new file mode 100644 index 00000000..2e3fbc22 --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/advanced/footer.mdx @@ -0,0 +1,76 @@ +# Footer + +Learn about configuring the two kinds of footers. + + +## The two footers + +Let's get the confusion out of the way first. There are two kinds of footers: +1. **Content footer:** This is the footer that is placed right below your content and doesn't go below the sidebar or table of contents. +2. **Page footer:** This footer is placed below everything, even under the content footer if you have both enabled. + + +## Configuring the content footer + +The content footer can hold 3 things: +- An "Edit this page on GitHub" link. +- Social links. Supported types: `slack`, `discord`, `x`, `mastodon`, `github`. +- Some text, by default it's a copyright notice. + +Here is an example of how to configure all of these, keep in mind that all fields are optional. + +```tsx title="theme.config.tsx" +import { site, social } from "@neato/guider/theme" + +site('site-a', { + contentFooter: { + socials: [ + social.x("https://x.com/"), + social.discord("https://discord.gg/"), + ], + text: "Made with <3", + + // edit repository base must point to the folder that the guider project is in. (same folder as the package.json) + // If it's in the root of the repository, make sure the url ends with /tree/BRANCHNAME + editRepositoryBase: "https://github.com/mrjvs/neatojs/tree/dev/apps/docs" + } +}) +``` + +Content footer is enabled by default, but in case you've customized it. It can be disabled/enabled even if you have the settings configured. +This can be done on any settings layout. Read more about [layout settings](/docs/guider/guides/config/theming#introduction-to-layout-settings) if you want. + +```tsx title="theme.config.tsx" +site('main', { + settings: { + contentFooter: true, + } +}) +``` + + +## Configuring the page footer + +The page footer can only hold text. However it is very easy to replace the footer with something custom. Read more about [customizing layout](/docs/guider/guides/advanced/customizing-layout). + +Here is an example of how to configure the text: + +```tsx title="theme.config.tsx" +import { site } from "@neato/guider/theme" + +site('site-a', { + pageFooter: { + text: 'Made with <3', + } +}) +``` + +**Page footer is disabled by default.** It will be disabled until explicitly enabled in the layout settings. Read more about [layout settings](/docs/guider/guides/config/theming#introduction-to-layout-settings) if you want. + +```tsx title="theme.config.tsx" +site('site-a', { + settings: { + pageFooter: true, + } +}) +``` diff --git a/apps/docs/pages/docs/guider/guides/advanced/header.mdx b/apps/docs/pages/docs/guider/guides/advanced/header.mdx new file mode 100644 index 00000000..32a4a35b --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/advanced/header.mdx @@ -0,0 +1,22 @@ +# Header + +Learn about configuring the page header. + +## Navigation + +If you are looking for ways to customise the navigation links in the header, you can [read more here](/docs/guider/guides/config/navigation). + +## Github widget + +To showcase your GitHub repository with its stars and forks, you can configure a GitHub widget. + +Simply add your username or organisation followed by a slash and your repo name: + +```tsx title="theme.config.tsx" +site('site-a', { + github: "mrjvs/neatojs", // [!code focus] + directories: [ + // ... + ] +}) +``` diff --git a/apps/docs/pages/docs/guider/guides/advanced/multi-site.mdx b/apps/docs/pages/docs/guider/guides/advanced/multi-site.mdx new file mode 100644 index 00000000..5a0f823a --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/advanced/multi-site.mdx @@ -0,0 +1,120 @@ +# Running multiple sites + +Managing big documentation sites or multiple at a time can be a challenge. On this page we talk about +the challenges and how to overcome them. + + +## The basics of running multiple sites + +Before we go over recommended techniques, let's first introduce the main method +on how to configure these sites. + +Sites in Guider don't neccesarily have completely seperate entities. Anything that is customized +beyond just the contents of the sidebar is a new site. Think of sites as just a new instance of a Guider site. + +A good use case of when to use a different site is if you want to have different content in the navigation header. + +--- + +Making new sites in Guider is thankfully very easy. Instead of just putting in one site configuration, you can enter an array: + +```tsx title="theme.config.tsx" showLineNumbers +import { site, defineTheme } from "@neato/guider/theme" + +export default defineTheme([ + site('site-a', {...}), // [!code focus] + site('site-b', {...}), // [!code focus] +]) +``` + + +## Site templates + +When you have many different sites that are mostly similar, it can be very verbose to reconfigure every site with the same settings. + +That is where site templates come in: you can make a template and any site can use a template as its base. + +```tsx title="theme.config.tsx" showLineNumbers +import { site, link, defineTheme, siteTemplate } from "@neato/guider/theme" + +const base = siteTemplate({ + navigation: [ + link("Example link", "/example"), + ] +}) + +export default defineTheme([ + site("site-a", { + extends: [base], + // ... other settings go here ... + }) +]) +``` + +You can provide multiple sites to extend from, they are merged in order of how they are passed in. + + + Arrays in template sites are overwritten completely and do not get merged together. + The only exception to this is layouts, all layouts are included in the final result. + + + +## Recommended folder structure + +Folder structure of your pages directory is completely flexible and up to the writer's choice. +However, below we have some recommendations for bigger projects. + +1. **Reserve a space for non-documentation:** It's likely that big documentation sites will expand slightly outside of purely documentation. +Think showcases, contact page, brand information. So it's wise to put your documentation on `/docs` so you can put everything else outside of it. +2. **Put your concepts all on one level:** When you have multiple concepts like a list of libraries or a list of applications. You should put all of them +in the same level. For example, for library `shoejs`, `jacketjs` and `sockdotnet`. You would have folders: `/docs/shoejs`, `/docs/jacketjs` and `docs/sockdotnet`. +Do not group them as `/docs/libs/xxx` or `/docs/apps/xxx`, it will only make it harder to find in your project structure with less predictable URLs. +3. **Have a `_meta.json` file at the root of every concept:** you should have a `_meta.json` file containing common configuration per concept. +Following the previous examples, put one at `/docs/shoejs/_meta.json`. with `{ "site": "shoejs" }{:json}`. +4. **Have a `theme.config.tsx` file at the root of every concept:** to prevent your site configuration from being gigantic, you can split it up per concept. +Create a theme config that just exports the single `site(...)` instance for that concept. At the top level `theme.config.tsx`, you can import them all and just add them to the `defineTheme()` + +To combine everything, here is the example folder structure from all the examples: +```sh +theme.config.tsx +pages/ +├── index.mdx +├── contact.mdx +└── docs/ + ├── shoejs/ + │ ├── _meta.json + │ ├── theme.config.tsx + │ ├── index.mdx + │ ├── getting-started/ + │ │ ├── install.mdx + │ │ ├── features.mdx + │ │ └── examples.mdx + │ └── usage/ + │ ├── basics.mdx + │ ├── advanced.mdx + │ └── contributing.mdx + ├── jacketjs/ + │ ├── _meta.json + │ ├── theme.config.tsx + │ ├── index.mdx + │ ├── getting-started/ + │ │ ├── install.mdx + │ │ ├── features.mdx + │ │ └── examples.mdx + │ └── usage/ + │ ├── basics.mdx + │ ├── advanced.mdx + │ └── contributing.mdx + └── sockdotnet/ + ├── _meta.json + ├── theme.config.tsx + ├── index.mdx + ├── getting-started/ + │ ├── install.mdx + │ ├── features.mdx + │ └── examples.mdx + └── usage/ + ├── basics.mdx + ├── advanced.mdx + └── contributing.mdx +``` diff --git a/apps/docs/pages/docs/guider/guides/config/common/api-ref.mdx b/apps/docs/pages/docs/guider/guides/config/common/api-ref.mdx new file mode 100644 index 00000000..e333fd0f --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/config/common/api-ref.mdx @@ -0,0 +1,5 @@ +# API reference + Docs + + +This article is a stub, please help by contributing to the docs. + diff --git a/apps/docs/pages/docs/guider/guides/config/common/blog.mdx b/apps/docs/pages/docs/guider/guides/config/common/blog.mdx new file mode 100644 index 00000000..fd1bbf10 --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/config/common/blog.mdx @@ -0,0 +1,5 @@ +# Blog posts + Docs + + +This article is a stub, please help by contributing to the docs. + diff --git a/apps/docs/pages/docs/guider/guides/config/common/multi-docs.mdx b/apps/docs/pages/docs/guider/guides/config/common/multi-docs.mdx new file mode 100644 index 00000000..72e595f9 --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/config/common/multi-docs.mdx @@ -0,0 +1,38 @@ +# Multiple documentation sites + +Unlike a lot of traditional documentation tools where you have to create multiple instances of the documentation for different sites (Whether that be versions, products, etc), in Guider you can create multiple "sites" within the same documentation. This means you do not have to maintain multiple documentation instances, and updating styling and common elements like headers and footers is much easier. + +There are many use cases when you might want to create multiple sites within the same documentation. For example, you might want to create a separate site for each product, or you might want to create a separate site for each version of a product. The NeatoJS documentation is a good example of this, where we have a separate site for each library (Take a look at the dropdown at the top left!). + + +Although sites can be good for lots of use cases, they are not suited for everything! Sites should only be used when you want to have a completely separate documentation. + +For example, if you would like a "Guide" and "API Reference", using directories and [tabs](/docs/guider/guides/config/navigation#adding-tabs) would be a better option. + + + +## Adding multiple sites to a project + +Sites are defined in Guider by adding a site to the `defineTheme` array in the `theme.config.tsx` file. Each site can have its own configuration including name, tabs, layouts and content. + +```tsx title="theme.config.tsx" showLineNumbers +import { site, defineTheme } from "@neato/guider/theme" + +export default defineTheme([ + site('site-a', {...}), // [!code focus] + site('site-b', {...}), // [!code focus] +]) +``` + + +## Making pages and folders use a specific site + +Once you have a set of pages made for a site, you will have to make sure that Guider knows which site to assign to your pages. +You can do this by making a `_meta.json` for your directory with your pages. Inside it, you can specify the site: +```json title="pages/my-site-b/_meta.json" +{ + "site": "site-b" +} +``` + +With this new file, all pages in the folder with the meta file (in this case it's `/pages/my-site-b`) and it's nested pages will belong to the site specified. diff --git a/apps/docs/pages/docs/guider/guides/config/examples.mdx b/apps/docs/pages/docs/guider/guides/config/examples.mdx new file mode 100644 index 00000000..8350ed3b --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/config/examples.mdx @@ -0,0 +1,9 @@ +# 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 new file mode 100644 index 00000000..07ff5080 --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/config/landing.mdx @@ -0,0 +1,74 @@ +# Landing page + +Landing pages are a good way to introduce your project without going directly into the documentation. +On this page you will learn how to make a landing page or use a preset. + + +## Creating a basic landing page + +To make a landing page (or any page that isn't MDX for that matter), you will first need to wrap it in a `{:tsx}` component. + +If you want the layout to belong to a specific layout or site, you can specify it the `meta` prop - this is completely optional. It accepts the same data as the Frontmatter from a page. + +```tsx title="index.mdx" showLineNumbers +import { GuiderLayout } from '@neato/guider/client'; + +export default function LandingPage() { + return ( + +

My page goes here

+ + ); +} +``` + +You can add any content you need inside of the `{:tsx}` component. + + +## Use premade landing page + +In the case that you don't want to put in extra effort into making a landing page, you can opt for using our premade landing page: + +```tsx title="index.mdx" showLineNumbers {12-38} +import { + Button, + Card, + CardGrid, + GuiderLayout, + Hero, +} from '@neato/guider/client'; + +export default function LandingPage() { + return ( + + + + Just went out of alpha! + + Documentation that looks great out of the box + + Flexible but beautiful documentation, easy to write and easier to + extend. Exactly what you need everytime. + + + + + + + + + Effortlessly create beautiful documentation sites with just markdown. + + + Effortlessly create beautiful documentation sites with just markdown. + + + Effortlessly create beautiful documentation sites with just markdown. + + + + ); +} +``` diff --git a/apps/docs/pages/docs/guider/guides/config/navigation.mdx b/apps/docs/pages/docs/guider/guides/config/navigation.mdx new file mode 100644 index 00000000..fd494d9c --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/config/navigation.mdx @@ -0,0 +1,108 @@ +# Navigation + +Guider has many possibilities in navigation. This page will go through +all methods and how to use them to their full potentional. + + +## Filling the sidebar + +The sidebar is the most expressive out of all the navigation structures. + +You can use the following components, all of which are imported from `@neato/guider/theme`. +- `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. +- `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. + + +Here is an example that uses every component. This sidebar configuration will +need to be added to the directory of your choosing. + +```tsx title="theme.config.tsx" +sidebar: [ + link("Link A", "/link/a"), + link("Link B with icon", "/link/b", { icon: 'fa6-solid:b' }), + link.nested("Link C in group", [ + link("Link C.1", "/link/c/1"), + link("Link C.2", "/link/c/2"), + ]), + link.nested("Link D in group", "/link/d", [ + link("Link D.1", "/link/d/1"), + link("Link D.2", "/link/d/2"), + ]), + link.nested("Title", [ + link("Title", "/link"), + ]), + group("Group A", [ + link("Link E", "/link/e"), + ]) + seperator(), + component(() =>

Custom component

), +] +``` + + +## Adding links to the header + +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. + +You can configure the top navigation per site. Here is an example that uses every component: + +```tsx title="theme.config.tsx" +site("my-site", { + navigation: [ + link("Link A", "/link/a"), + link("Link B with icon", "/link/b", { icon: 'fa6-solid:b' }), + seperator(), + link("Link C", "/link/c"), + ] +}) +``` + + +## Adding tabs + +Sometimes you want to split up your documentation site into multiple sections. As an example, you can split it up between "Documentation" and "API reference". That's a perfect case for tabs. + +You can use the following components, all of which are imported from `@neato/guider/theme`. +- `link(){:ts}`: A standard tab with optional icon. +- `component(){:ts}`: A custom component, you can render any React component in here. + +You can configure tabs per site, here is an example that uses every component: + +```tsx title="theme.config.tsx" +site("my-site", { + tabs: [ + link("Link A", "/link/a"), + link("Link B", "/link/b"), + component(() =>

Custom component

), + ] +}) +``` + + +## A dropdown for your sites + +In cases where you have multiple projects, all with seperate documentation sites, the dropdown may be a better fit than links in the top navigation. + +You can use the following components, all of which are imported from `@neato/guider/theme`. +- `link(){:ts}`: A standard dropdown with optional icon. + +You can configure the dropdown per site, here is an example that uses every component: + +```tsx title="theme.config.tsx" +site("my-site", { + dropdown: [ + link("Link A", "/link/a"), + link("Link B", "/link/b"), + ] +}) +``` diff --git a/apps/docs/pages/docs/guider/guides/config/redirects.mdx b/apps/docs/pages/docs/guider/guides/config/redirects.mdx new file mode 100644 index 00000000..911ef08f --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/config/redirects.mdx @@ -0,0 +1,21 @@ +# Redirects + +Sometimes, you want to redirect from a link to a page. For example, redirecting from `/docs` to an actual page like `/docs/getting-started`. + +Next.JS does not provide an easy way if you render as a static site. So Guider has a simple tool to orchestrate redirects. + +## Creating a redirect + +The `createRedirect` function can make a page that simply redirects to another page. +So for example above, you would make a `docs/index.mdx` file with the following: + +```ts title="docs/index.mdx" +import { createRedirect } from '@neato/guider/client' + +export default createRedirect({ to: '/docs/getting-started' }); +``` + + +Some hosting platforms like Netlify or Cloudflare Pages can give you more control over redirects with a `_redirects` file.
+This is preferable over `createRedirect` since it uses HTTP redirection instead of Javascript. + diff --git a/apps/docs/pages/docs/guider/guides/config/seo.mdx b/apps/docs/pages/docs/guider/guides/config/seo.mdx new file mode 100644 index 00000000..3d536efd --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/config/seo.mdx @@ -0,0 +1,74 @@ +# SEO & Meta tags + +SEO is important to make your docs discoverable by search engine. By default, Guider does not provide much metadata. However it does make it very easy to add them through [Next SEO](https://github.com/garmeeh/next-seo). + +## The basics + +Page titles and descriptions can be set by creating a [frontmatter](https://jekyllrb.com/docs/front-matter/) section at the top of your MDX file. + +```mdx title="page.mdx" +--- +title: "My title" +description: "My page description" +--- +# A title +Some text +``` + + +Both title and description are optional. If there are not specified, the title will be the first heading on the page and the description will be the first paragraph on the page. + + +## Adding custom meta tags + +If you want to add more meta tags, you can do so by passing an object to the site options. You can check all the different options on the [Next SEO Options](https://github.com/garmeeh/next-seo?tab=readme-ov-file#nextseo-options) page. +```ts +site('my-site', { + meta: { + titleTemplate: "%s - Guider", + openGraph: { + type: 'website', + url: 'https://www.example.com/page', + title: 'My site', + description: 'My description' + } + } +}) +``` + +In the case that you need more flexibility in meta tags or need to add [JSON-LD](https://github.com/garmeeh/next-seo?tab=readme-ov-file#json-ld), you can provide a function that returns a component, which can make use of the `useGuiderPage()` hook. +You will need to install `next-seo` into your project to use this method. + +As the only parameter, default meta tags are passed into your function. + +```tsx +import { BreadcrumbJsonLd, NextSeo } from 'next-seo'; +import { useGuiderPage } from '@neato/guider/client'; + +site('my-site', { + meta(pageMeta) { + const { site } = useGuiderPage(); + return ( + <> + + + + ); + } +}); +``` + + +When you're using a function to render the meta tags, the default meta tags aren't added. You will need to add them yourself as shown in the example. + diff --git a/apps/docs/pages/docs/guider/guides/config/theming.mdx b/apps/docs/pages/docs/guider/guides/config/theming.mdx new file mode 100644 index 00000000..cec3e1b1 --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/config/theming.mdx @@ -0,0 +1,122 @@ +# Colors & theme + +Guider has been designed fit almost any use case for documentation. +Naturally, this means that there are lots of configuration options to provide the flexibility Guider offers. + +Usually, the first thing to change is the branding. + +## Introduction to layout settings + +Layout settings can be modified on three layers, each one overriding settings from a previous layer. The layers are as follows: +- **Site layout settings:** The base layer of layout settings is simply on `Site.settings`. +- **Layout settings:** The second layer that counts is on a layout itself at `Layout.settings`. +- **Directory layout settings:** The last layer is on a directory at `Directory.settings`. + +All of these layers are resolved in order. So if you have something specified on the directory layer, it will overwrite all other layers. +If you specify something on the layout layer, it will overwrite the site layer but not the directory layer. + +```ts title="Layer examples" +site('main', { + settings: { + toc: false, + sidebar: false, + } + directories: [ + directory("main", { + layout: "test-layout" + sidebar: [ + link("Home", "/") + ], + settings: { + toc: false, + } + }) + ], + layouts: [ + layout('test-layout', { + settings: { + toc: true, + sidebar: true, + } + }) + ] +}) +``` + +In this example, the final result will be `toc == false{:ts}` because the directory settings have the highest priority and `sidebar == true{:ts}` because the settings in layouts are a higher priority than the site settings. + +## Changing colors + +Now that you know how layout settings are resolved. We can start customising the colors and other layout settings: + +```ts +settings: { + colors: { + // Main theme colors + primary: '#50A0EA', // Primary color of the site + primaryDarker: '#1B65A9', // A darker variant of primary color + primaryLighter: '#89C6FF', // A lighter variant of the primary color + text: '#668896', // Normal text color + textLighter: '#9AB3BD', // Slightly lighter text color + textHighlight: '#FFFFFF', // Heading and highlight text color. + background: '#050F13', // Main page background color + backgroundLighter: '#07171C', // Lighter background color for code blocks and such + backgroundLightest: '#081E24', // Lightest background color for hover effects + backgroundDark: '#040C0F' // Darker variant of the background color + line: '#0F2B33', // Color of all lines + + // Colors in code blocks + codeWarning: '#222D20', // Codeblock background for a warning annotation + codeError: '#2B1B1F', // Codeblock background for a error annotation and diff remove + codeGreen: '#0B2823', // Codeblock background for a diff add + codeHighlight: '#0E2429', // Codeblock background for a highlighted line + codeWordHighlight: '#365C68', // Background of a highlighted word in a codeblock + + // Semantic colors - Primarily used in callouts + // The lighter variants are used for text colors in callouts + semanticTip: '#39B864', + semanticTipLighter: '#75F2B6', + semanticNote: '#817EF3', + semanticNoteLighter: '#B9B8FC', + semanticImportant: '#A958E8', + semanticImportantLighter: '#D3A2F9', + semanticWarning: '#C0BC43', + semanticWarningLighter: '#ECE873', + semanticCaution: '#FC6359', + semanticCautionLighter: '#FFA59F', + } +} +``` + +## Changing the logo + +If just want to modify the site name and homepage link, you can simple change it in site configuration: +```ts +site('site-id', { + logo: { + to: '/', + name: 'My docs' + }, + // ... other settings +}) +``` + +If you want to fully customize how your logo looks (For example, using an image as your logo), you can overwrite the full partial in **any settings layer**: +```tsx +settings: { + logo:

My logo

+} +``` + + +## Enabling the background pattern + +You can optionally enable a fancy looking background pattern. It uses your configured primary colors. + +```tsx +settings: { + backgroundPattern: 'flare' +} +``` + +There are currently no other options other than `flare` and just having it disabled. diff --git a/apps/docs/pages/docs/guider/guides/deploy/cloudflare.mdx b/apps/docs/pages/docs/guider/guides/deploy/cloudflare.mdx new file mode 100644 index 00000000..c77061d7 --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/deploy/cloudflare.mdx @@ -0,0 +1,5 @@ +# Cloudflare Pages + + +This article is a stub, please help by contributing to the docs. + diff --git a/apps/docs/pages/docs/guider/guides/deploy/docker.mdx b/apps/docs/pages/docs/guider/guides/deploy/docker.mdx new file mode 100644 index 00000000..045fb487 --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/deploy/docker.mdx @@ -0,0 +1,36 @@ +# Docker + +A Dockerfile to build a Guider documentation site container. + + +## The code + +Add the following code to a file called `Dockerfile`. **It has to be in the same location as your package.json.** + +If you're running a monorepo or using private packages, this file won't help. You'll be on your own to figure it out. +Also if you're using a different package manager, you'll have to change the file to use your specific manager. + +```dockerfile title="Dockerfile" +FROM node:20-alpine as build +WORKDIR /app + +COPY package*.json ./ +RUN npm ci + +COPY . ./ +RUN npm run build + +FROM nginx:1.25-alpine as run +EXPOSE 80 +RUN cat > /etc/nginx/nginx.conf << EOF +server { + listen 80; + + location / { + root /usr/share/nginx/html; + try_files $uri /404.html; + } +} +EOF +COPY --from=build /app/out /usr/share/nginx/html +``` diff --git a/apps/docs/pages/docs/guider/guides/deploy/github-pages.mdx b/apps/docs/pages/docs/guider/guides/deploy/github-pages.mdx new file mode 100644 index 00000000..58582def --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/deploy/github-pages.mdx @@ -0,0 +1,67 @@ +# Github Pages + +A Github Action to deploy a Guider documentation site. + +## Prerequisites + +- Enable Github Pages, go to `Your repo > Settings > Pages` and set `Source` to `Github Actions`. + +## The workflow + +Add this code to a file in the github workflows folder, for example: `/.github/workflows/docs-deploy.yml`. + +There are highlighted words in the code, double check if those match your environment. +This code sample assumes you use `npm`, with the branch `main` as your release branch and the docs being in the root of your repository. + +```yml title=".github/workflows/docs-deploy.yml" +name: "docs-deploy" + +on: + push: + branches: + # [!code word:main:1] + - main + +jobs: + build: + name: Build + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + # [!code word:npm] + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: 'npm' + + # [!code word:./] + - name: Install dependencies + working-directory: ./ + run: npm ci + + - name: Build + working-directory: ./ + run: npm run build + + - name: Upload + uses: actions/upload-pages-artifact@v3 + working-directory: ./ + with: + path: out + + deploy: + needs: build + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 +``` diff --git a/apps/docs/pages/docs/guider/guides/deploy/netlify.mdx b/apps/docs/pages/docs/guider/guides/deploy/netlify.mdx new file mode 100644 index 00000000..11e9835e --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/deploy/netlify.mdx @@ -0,0 +1,5 @@ +# Netlify + + +This article is a stub, please help by contributing to the docs. + diff --git a/apps/docs/pages/docs/guider/guides/deploy/vercel.mdx b/apps/docs/pages/docs/guider/guides/deploy/vercel.mdx new file mode 100644 index 00000000..1cacc42b --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/deploy/vercel.mdx @@ -0,0 +1,5 @@ +# Vercel + + +This article is a stub, please help by contributing to the docs. + diff --git a/apps/docs/pages/docs/guider/guides/getting-started/development.mdx b/apps/docs/pages/docs/guider/guides/getting-started/development.mdx new file mode 100644 index 00000000..5f3c1d2e --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/getting-started/development.mdx @@ -0,0 +1,33 @@ +# Development + +This guide goes over some tips to get the optimal developer experience for writing your documentation. + + +## Running the development server + +After you've gone through the installation process, all you need to do get up and running is +run the dev script with your favourite package manager. For an example with NPM: + +```sh +npm run dev +``` + + +The Next.JS development server is infamous for being slow. The final build of the site will be **much** faster. + + + +## Building for production + +To build your production build, you can run `npm run build{:sh}` (or use your favourite package manager). + +This will create a folder called `out` that holds the final build that's ready for deployment. + +If you want to preview it, you can run `npx run serve out` to spin up a temporary HTTP server that serves the `out` folder. + + +## Autocomplete and syntax highlighting for MDX files + +By default, most code editors will not support MDX files. To add support, you can install the MDX extensions: + - For JetBrains editors, you can use the JetBrains maintained [MDX plugin](https://plugins.jetbrains.com/plugin/14944-mdx). + - For VSCode, you can install the [MDX extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) maintained by the MDX team. diff --git a/apps/docs/pages/docs/guider/guides/getting-started/installation.mdx b/apps/docs/pages/docs/guider/guides/getting-started/installation.mdx new file mode 100644 index 00000000..7ef69ddd --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/getting-started/installation.mdx @@ -0,0 +1,203 @@ +# Getting started with Guider + +Guider is built on top of Next.JS, this gives you the flexibilty to include +it as part of a normal React app built with Next.JS. + +Get started with `@neato/guider` project in under 5 minutes. + +## Installation + + + + The fastest way to setup a new Next.JS project is with the create-next-app tool [provided by Next.JS](https://nextjs.org/docs/getting-started/installation). + + + + ### Create a Next.JS project + Since Guider is essentially a plugin of Next.JS, You will need to install Next.JS normally. + To automatically create a new Next.JS app, run: + ```sh + npx create-next-app@latest + ``` + + + ### Add a Next.JS config + Create or replace the following `next.config.js` file in your project's root directory. + ```js title="next.config.js" showLineNumbers + const { guider } = require('@neato/guider'); + + const withGuider = guider({ + // The location of your theme file, created in the next step + themeConfig: './theme.config.tsx', + }); + + module.exports = withGuider({ + // These are the normal Next.JS settings. + // Check out Next.JS docs: https://nextjs.org/docs/app/api-reference/next-config-js + output: 'export', + }); + ``` + + + ### Create a theme config + Finally, create a `theme.config.tsx`. This will be the home for all of your configuration and customization of Guider: + ```ts title="theme.config.tsx" showLineNumbers + import { defineTheme, directory, link } from '@neato/guider/theme'; + + export default defineTheme( + site('main', { // ID of your site, used for referencing in other files + directories: [ + directory("main", {// ID of your directory (unique per site), used for referencing in other files + sidebar: [ + // Creates a link in your sidebar, add more below it + link("Home", "/") + ] + }) + ], + }) + ); + ``` + + + ### Create entrypoint files + Next, create two files `pages/_app.tsx` and `pages/404.tsx`. They should be in your pages directory. + The app file is used to import the global styles for Guider. The 404 file holds a preset "page not found" view, feel free to customize it. + + + ```tsx + import '@neato/guider/style.css'; + import { createGuiderApp } from '@neato/guider/client'; + + export default createGuiderApp(); + ``` + + + ```tsx + import { createNotFoundPage } from '@neato/guider/client'; + + export default createNotFoundPage(); + ``` + + + + + ### Ready to write documentation! + Your project has been fully setup, all that's left is to fill it with content. Try it out by making a file in your pages directory: + ```md title="pages/index.mdx" + # Hello world + This is my first `@neato/guider` page! + ``` + And run with `npm run dev{:sh}` and see your first page by visiting the link shown in the console. + + The Next.JS development server is infamous for being slow. The final build of the site will be **much** faster. + + + + + + + + If you want to integrate the Next.JS project into an existing folder or want
+ to be more aware of what is happening under the hood. The manual install will be a better fit. + + + + ### Create a Next.JS project + To install a Next.JS project manually, install the following dependencies: + ```sh npm2yarn + npm install next@latest react@latest react-dom@latest + ``` + then add the following scripts to your `package.json`: + ```json title="package.json" showLineNumbers + { + "scripts": { + "dev": "next dev", + "build": "next build", + "start": "next start", + "lint": "next lint" + } + } + ``` + + + ### Add a Next.JS config + Create or replace the following `next.config.js` file in your project's root directory. + ```js title="next.config.js" showLineNumbers + const { guider } = require('@neato/guider'); + + const withGuider = guider({ + // The location of your theme file, created in the next step + themeConfig: './theme.config.tsx', + }); + + module.exports = withGuider({ + // These are the normal Next.JS settings. + // Check out Next.JS docs: https://nextjs.org/docs/app/api-reference/next-config-js + output: 'export', + }); + ``` + + + ### Create a theme config + Next, create a `theme.config.tsx`. This will be the home for all of your configuration and customization of Guider: + ```ts title="theme.config.tsx" showLineNumbers + import { defineTheme, directory, link } from '@neato/guider/theme'; + + export default defineTheme({ + id: "main", // ID of your site, used for referencing in other files + directories: [ + directory({ + id: "main", // ID of your directory (unique per site), used for referencing in other files + sidebarItems: [ + // Creates a link in your sidebar, add more below it + link("Home", "/") + ] + }) + ], + }); + ``` + + + ### Create entrypoint files + Finally, create two files `pages/_app.tsx` and `pages/404.tsx`. They should be in your pages directory. + The app file is used to import the global styles for Guider. The 404 file holds a preset "page not found" view, feel free to customize it. + + + ```tsx + import '@neato/guider/style.css'; + import { createGuiderApp } from '@neato/guider/client'; + + export default createGuiderApp(); + ``` + + + ```tsx + import { createNotFoundPage } from '@neato/guider/client'; + + export default createNotFoundPage(); + ``` + + + + + ### Ready to write documentation! + Your project has been fully setup, all that's left is to fill it with content. Try it out by making a file in your pages directory: + ```md title="pages/index.mdx" + # Hello world + This is my first `@neato/guider` page! + ``` + And run with `npm run dev{:sh}` and see your first page by visiting the link shown in the console. + + The Next.JS development server is infamous for being slow. The final build of the site will be **much** faster. + + + + + + +## What's next? + +You have everything setup now. To get acquainted with Guider. You can take the follow steps: +- Learn how to [setup navigation](../config/navigation.mdx). +- Check out the basics of [writing content](../../writing/markdown/basic-text.mdx). +- Find out how to [deploy your site](../deploy/github-pages.mdx). 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 new file mode 100644 index 00000000..6a1cf8d0 --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/getting-started/migration/from-docus.mdx @@ -0,0 +1,5 @@ +# Migrating from Docus + + +This article is a stub, please help by contributing to the docs. + 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 new file mode 100644 index 00000000..60b816c8 --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/getting-started/migration/from-mintlify.mdx @@ -0,0 +1,5 @@ +# Migrating from Mintlify + + +This article is a stub, please help by contributing to the docs. + 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 new file mode 100644 index 00000000..13c1c359 --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/getting-started/migration/from-nextra.mdx @@ -0,0 +1,5 @@ +# Migrating from Nextra + + +This article is a stub, please help by contributing to the docs. + diff --git a/apps/docs/pages/docs/guider/guides/index.mdx b/apps/docs/pages/docs/guider/guides/index.mdx deleted file mode 100644 index 599ca37a..00000000 --- a/apps/docs/pages/docs/guider/guides/index.mdx +++ /dev/null @@ -1,3 +0,0 @@ -# Welcome to Guider - -Nothing is here yet, check back later! diff --git a/apps/docs/pages/docs/guider/guides/index.tsx b/apps/docs/pages/docs/guider/guides/index.tsx new file mode 100644 index 00000000..28fe7260 --- /dev/null +++ b/apps/docs/pages/docs/guider/guides/index.tsx @@ -0,0 +1,5 @@ +import { createRedirect } from '@neato/guider/client'; + +export default createRedirect({ + to: '/docs/guider/guides/getting-started/installation', +}); diff --git a/apps/docs/pages/docs/guider/guides/test.mdx b/apps/docs/pages/docs/guider/guides/test.mdx deleted file mode 100644 index 599ca37a..00000000 --- a/apps/docs/pages/docs/guider/guides/test.mdx +++ /dev/null @@ -1,3 +0,0 @@ -# Welcome to Guider - -Nothing is here yet, check back later! diff --git a/apps/docs/pages/docs/guider/index.tsx b/apps/docs/pages/docs/guider/index.tsx index 96cb9d8f..4db786d4 100644 --- a/apps/docs/pages/docs/guider/index.tsx +++ b/apps/docs/pages/docs/guider/index.tsx @@ -1,3 +1,41 @@ -import { createRedirect } from '@neato/guider/client'; +import { + Button, + Card, + CardGrid, + GuiderLayout, + Hero, +} from '@neato/guider/client'; -export default createRedirect({ to: '/docs/guider/docs' }); +export default function LandingPage() { + return ( + + + + Just went out of alpha! + + Documentation that looks great out of the box + + Flexible but beautiful documentation, easy to write and easier to + extend. Exactly what you need everytime. + + + + + + + + + Effortlessly create beautiful documentation sites with just markdown. + + + Effortlessly create beautiful documentation sites with just markdown. + + + Effortlessly create beautiful documentation sites with just markdown. + + + + ); +} diff --git a/apps/docs/pages/docs/guider/writing/advanced/dividers.mdx b/apps/docs/pages/docs/guider/writing/advanced/dividers.mdx new file mode 100644 index 00000000..796aa764 --- /dev/null +++ b/apps/docs/pages/docs/guider/writing/advanced/dividers.mdx @@ -0,0 +1,46 @@ +# Dividers + +Learn how to add divider lines to your documentation. + +## The syntax + +Dividers can be a nice way to section up your content outside of just headings. Thankfully markdown has a very easy syntax to make dividers. + +If you add three or more asterisks (`***`), dashes (`---`) or underscores (`___`). A divider will appear. + + +
+ +Some text + +--- + +More text +___ + +Even more text + +*** + +Final text +
+ + +```md +Some text + +--- + +More text +___ + +Even more text + +*** + +Final text +``` + + +Make sure to add blank lines around a divider. If a divider is directly under a paragraph, the paragraph will be interpreted as a heading. + diff --git a/apps/docs/pages/docs/guider/writing/advanced/footnotes.mdx b/apps/docs/pages/docs/guider/writing/advanced/footnotes.mdx new file mode 100644 index 00000000..6f233aef --- /dev/null +++ b/apps/docs/pages/docs/guider/writing/advanced/footnotes.mdx @@ -0,0 +1,24 @@ +# Footnotes + +Learn how to add footnotes to your documentation. + +## The syntax + +You can add footnotes to your page with a bracket syntax. Add `[^1]{:md}` somewhere in your text, and somewhere else you can add a line `[^1]: My reference{:md}` to add content to the footnote. + + +As Linus Torvalds once said: +"Most of the good programmers do programming not because they expect to get paid or get adulation by the public, but because it is fun to program."[^1]. + +[^1]: [Interview with Linus Torvalds](https://firstmonday.org/ojs/index.php/fm/article/view/583/504) on what motivates software developers. + +```md +As Linus Torvalds once said: +"Most of the good programmers do programming not because they expect to get paid or get adulation by the public, but because it is fun to program."[^1]. + +[^1]: [Interview with Linus Torvalds](https://firstmonday.org/ojs/index.php/fm/article/view/583/504) on what motivates software developers. +``` + + +The position of the footnote does not matter, it is always shown at the bottom of your page. + diff --git a/apps/docs/pages/docs/guider/writing/advanced/quotes.mdx b/apps/docs/pages/docs/guider/writing/advanced/quotes.mdx new file mode 100644 index 00000000..3583b3bf --- /dev/null +++ b/apps/docs/pages/docs/guider/writing/advanced/quotes.mdx @@ -0,0 +1,29 @@ +# Quotes + +Learn how to add quote blocks to your documentation. + + +## Basic quotes + +To create a quote block, simply add a `>` in front of your text. + +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. + +```md +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +``` + + +## Multi-line quotes + +Creating multi-line quotes is just as easy as normal quotes. Just keep adding more `>` add the start of the lines. + +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> +> Donec non dapibus mauris. + +```md +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> +> Donec non dapibus mauris. +``` diff --git a/apps/docs/pages/docs/guider/writing/advanced/tables.mdx b/apps/docs/pages/docs/guider/writing/advanced/tables.mdx new file mode 100644 index 00000000..865763ce --- /dev/null +++ b/apps/docs/pages/docs/guider/writing/advanced/tables.mdx @@ -0,0 +1,72 @@ +# Tables + +Tables are useful to display structured data. + + +## Basic table + +Tables in Guider use the standard [markdown syntax](https://www.markdownguide.org/extended-syntax/#tables). You can use any inline styling +inside of tables such as inline code, bolding and italics. + +| Name | Hobby | +| -------- | --------------------------------------- | +| John | Ultimate Frisbee | +| Jane | Building Guitars | +| Mark | Experimenting with very wet bread dough | + +```md +| Name | Hobby | +| -------- | --------------------------------------- | +| John | Ultimate Frisbee | +| Jane | Building Guitars | +| Mark | Experimenting with very wet bread dough | +``` + +You can make cell widths different sizes, the output will be the same: + +```md +| Name | Hobby | +| --- | --- | +| John | Ultimate Frisbee | +| Jane | Building Guitars | +| Mark | Experimenting with very wet bread dough | +``` + + +Need to use the pipe symbol (`|`) inside your table? Prefix it with a backslash (`\`) to make it count as cell content instead of a divider. + + +## Empty headers + +Table headers in markdown are required, but if you leave them completely empty (only spaces). Guider will hide the header row for you. + +| | | +| -------- | ---------------------------------- | +| John | Ultimate Frisbee | +| Jane | Building Guitars | +| Mark | Experimenting very wet bread dough | + +```md +| | | +| -------- | ---------------------------------- | +| John | Ultimate Frisbee | +| Jane | Building Guitars | +| Mark | Experimenting very wet bread dough | +``` + + +## Alignment + +You can align the contents of a column in a specific direction by adding a colon (`:`) to the left, right or both sides of the hyphens in the header row. + +| Left | Center | Right | +| :---- | :----: | ----: | +| Lorem | Ipsum | Dolor | +| Sit | Samet | Elit | + +```md +| Left | Center | Right | +| :---- | :----: | ----: | +| Lorem | Ipsum | Dolor | +| Sit | Samet | Elit | +``` diff --git a/apps/docs/pages/docs/guider/writing/components/callouts.mdx b/apps/docs/pages/docs/guider/writing/components/callouts.mdx new file mode 100644 index 00000000..85767ece --- /dev/null +++ b/apps/docs/pages/docs/guider/writing/components/callouts.mdx @@ -0,0 +1,63 @@ +# Callouts + +Need to make the reader aware of something in context to your documentation? Callouts are a nice looking way to do so. + + +## General usage + +Callouts are usually contain a sentence or two, but they aren't that limited. +You can put any content in callouts: headings, multiple paragraphs, bold text and even custom components. + + +## A note + +Notes are good for adding extra information that may not fit in a sentence. + +```jsx +Notes are good for adding extra information that may not fit in a sentence. +``` + + +## An important callout + +Important callouts are great for conveying an important extra step + +```jsx +Important callouts are great for conveying an important extra step +``` + + +## A tip + +Tips are amazing for giving helpful shortcuts + +```jsx +Tips are amazing for giving helpful shortcuts +``` + + +## A warning + +Warnings are splendid to convey edgecases or unexpected behaviour + +```jsx +Warnings are splendid to convey edgecases or unexpected behaviour +``` + + +## A caution + +Cautions are superb to get the readers attention to something critical + +```jsx +Cautions are superb to get the readers attention to something critical +``` + + +## General component + +In case you need to dynamically change the type of the callout, you can use the `{:tsx}` component. You can specify the `type` prop to set the style. + +```jsx +I am a callout +``` diff --git a/apps/docs/pages/docs/guider/writing/components/code-groups.mdx b/apps/docs/pages/docs/guider/writing/components/code-groups.mdx new file mode 100644 index 00000000..cfb08cf9 --- /dev/null +++ b/apps/docs/pages/docs/guider/writing/components/code-groups.mdx @@ -0,0 +1,80 @@ +# Code groups + +Code groups are a great way to group multiple codeblocks together, for example when +you need to showcase multiple files. It's also a great way to show previews of code. + + +## General usage + +To make a code group, simply add a `{:tsx}` component, with any number of `{:tsx}` inside it. + +The `{:tsx}` will need a title and should only contain codeblocks or `{:tsx}` components. Only put in one codeblock or `{:tsx}` inside at a time. + +````tsx + + + ```ts + export function hello() { + return "world"; + } + ``` + + + ```ts + import { hello } from "./test"; + + console.log(hello()); + ``` + + +```` + + + + ```ts + export function hello() { + return "world"; + } + ``` + + + ```ts + import { hello } from "./test"; + + console.log(hello()); + ``` + + + + +## Combining with Frames + +Codegroup children can also contain `` components. See the example below. + +````tsx + + + ```tsx + + ``` + + + + + + + +```` + + + + ```tsx + + ``` + + + + + + + diff --git a/apps/docs/pages/docs/guider/writing/components/custom.mdx b/apps/docs/pages/docs/guider/writing/components/custom.mdx new file mode 100644 index 00000000..10260795 --- /dev/null +++ b/apps/docs/pages/docs/guider/writing/components/custom.mdx @@ -0,0 +1,58 @@ +import { useState, useCallback } from "react"; +import { Button } from "@neato/guider/client"; + +# Custom components + +Custom components are a way to taylor your documentation to your product. + + +## Making a custom component + +Since Guider uses [MDX](https://mdxjs.com/), you can use any React components in your pages. + +Here is an example of a simple custom component: + + + + ```ts + import { useState, useCallback } from "react"; + import { Button } from "@neato/guider/client"; + + export function Counter() { + const [num, setNum] = useState(1); + const increase = useCallback(() => { + setNum(v => v + 1); + }, []) + + return ; + } + ``` + + + ```tsx + import { Counter } from "../components/counter.tsx"; + + # My counter + + Look at my counter: + + ``` + + + +export function Counter() { + const [num, setNum] = useState(1); + const increase = useCallback(() => { + setNum(v => v + 1); + }, []) + + return ; +} + + + + + + + Learn how to make React components with this [official React guide](https://react.dev/learn#components) + diff --git a/apps/docs/pages/docs/guider/writing/components/frames.mdx b/apps/docs/pages/docs/guider/writing/components/frames.mdx new file mode 100644 index 00000000..6f2be991 --- /dev/null +++ b/apps/docs/pages/docs/guider/writing/components/frames.mdx @@ -0,0 +1,37 @@ +# Frames + +Frames are a good way to showcase UI components, images or basically anything that needs to be framed. + + +## General usage + +Frames are super simple to use, simply wrap your content in a `{:tsx}` component. See the example below: + +````tsx + + + +```` + + + + + + +## Prevent centering + +If you don't want something to be centered. You can wrap your content in `
{:tsx}` before putting it in a frame: + +````tsx + +
+ +
+ +```` + + +
+ +
+ diff --git a/apps/docs/pages/docs/guider/writing/components/steps.mdx b/apps/docs/pages/docs/guider/writing/components/steps.mdx new file mode 100644 index 00000000..e37309ff --- /dev/null +++ b/apps/docs/pages/docs/guider/writing/components/steps.mdx @@ -0,0 +1,34 @@ +# Steps + +If you have a number of steps for a reader to follow, the steps component is a great choice. + + +## General usage + +You can make steps by making a container `{:tsx}` component with any number of `{:tsx}` inside them. + +You can put any content inside of a step, so don't feel restricted to just text. Steps work great with a level 3 heading as the first element. + +````tsx + + + ### Step one + Step content goes here + + + ### Step two + Step content goes here + + +```` + + + + ### Step one + Step content goes here + + + ### Step two + Step content goes here + + diff --git a/apps/docs/pages/docs/guider/writing/components/tabs.mdx b/apps/docs/pages/docs/guider/writing/components/tabs.mdx new file mode 100644 index 00000000..5b9a6b6a --- /dev/null +++ b/apps/docs/pages/docs/guider/writing/components/tabs.mdx @@ -0,0 +1,88 @@ +# Tabs + +If you would like different variants or subsections to be toggleable, the tab element may be your best fit. + + +## General usage + +Tabs are made by wrapping each tab's content in a `{:tsx}` element. All tabs are then enclosed in a container element (`{:tsx}`). + +The container element needs a list of navigation items that match the number of tabs. For example: `{:tsx}`. See the full example below. + +You can put any content inside of a tab, so don't feel restricted to just text. + +````tsx + + + Tab A + + + Tab B + + + Tab C + + +```` + + + + Tab A + + + Tab B + + + Tab C + + + + +## Default tab + +You can set a default tab which is the tab that is selected before the reader chooses a specific one. + +The counter starts at 0. This means the first tab is index 0, the second tab index 1 and so on. + +````tsx + + ... + +```` + + + + Tab A + + + Tab B + + + Tab C + + + + +## Storing the tab choice + +By default, the reader's tab choice is not persistent. When they switch to a different page, the tab choice is forgotten and next time they visit the page it will be the default again. + +If you would like the user's choice to be stored, you can give a `storageKey` prop. **If you give two or more tabs the same storage key, it will synchronize the tabs. Switching tab on one will also switch on the others.** + +````tsx + + ... + +```` + + + + Tab A + + + Tab B + + + Tab C + + diff --git a/apps/docs/pages/docs/guider/writing/index.mdx b/apps/docs/pages/docs/guider/writing/index.mdx deleted file mode 100644 index 599ca37a..00000000 --- a/apps/docs/pages/docs/guider/writing/index.mdx +++ /dev/null @@ -1,3 +0,0 @@ -# Welcome to Guider - -Nothing is here yet, check back later! diff --git a/apps/docs/pages/docs/guider/writing/index.tsx b/apps/docs/pages/docs/guider/writing/index.tsx new file mode 100644 index 00000000..a47be999 --- /dev/null +++ b/apps/docs/pages/docs/guider/writing/index.tsx @@ -0,0 +1,5 @@ +import { createRedirect } from '@neato/guider/client'; + +export default createRedirect({ + to: '/docs/guider/writing/markdown/making-pages', +}); diff --git a/apps/docs/pages/docs/guider/writing/markdown/basic-text.mdx b/apps/docs/pages/docs/guider/writing/markdown/basic-text.mdx new file mode 100644 index 00000000..60cbd609 --- /dev/null +++ b/apps/docs/pages/docs/guider/writing/markdown/basic-text.mdx @@ -0,0 +1,54 @@ +# Basic text + +Learn the basics of Markdown through this simple guide. + + +## Paragraphs + +Writing paragraphs in markdown is very easy, you just write a line of text. + +If you want to start a new paragraph, make sure you add **two** newlines instead of one. + +```md +This is the first paragraph. + +And this is the second paragraph! +``` + + +## Titles + +```md +# Page title + +## Section title + +### Subtitle +``` + + + All Section titles show up in the Table of Contents on the right. + + + +## Text formatting + +Almost all markdown formatting is supported in Guider, simply wrap your text in the appropiate symbols. + +| Formatting | Markdown down | Result | +|---------------|--------------------------|------------------------| +| Bold | `**Bold**` | **Bold** | +| Italic | `_Italic_` | _Italic_ | +| Strikethrough | `~Strikethrough~` | ~Strikethrough~ | +| Superscript | `Superscript` | Superscript | +| Subscript | `Subscript` | Subscript | + +You can combine multiple styles. For example `**_Bold and italic_**` to get **_Bold and italic_**. + + +## Linking to other pages + +You can link to other pages simply by wrapping your text in `[]()`. For example, to link to an external website you would write `[Example](https://example.com)` which would look like +this: [Example](https://example.com). + +If you need to link to other internal pages you can write `[Link text](../page-a)` or the full path: `[link text](/docs/page-b)`. diff --git a/apps/docs/pages/docs/guider/writing/markdown/code-blocks.mdx b/apps/docs/pages/docs/guider/writing/markdown/code-blocks.mdx new file mode 100644 index 00000000..74275eca --- /dev/null +++ b/apps/docs/pages/docs/guider/writing/markdown/code-blocks.mdx @@ -0,0 +1,216 @@ +# Code blocks + +If you're writing technical documentation, code blocks are essential. This is why Guider code blocks are jam-packed with features. + + +## Basic code block + +Code blocks are very easy to write in Markdown. Simply wrap your code in 3 backticks (```) in front and 3 after. +Optionally you can specify a programming language directly after the first 3 backticks for the code to be syntax highlighted. + +```js +console.log("hello world") +``` + +````md +```js +console.log("hello world") +``` +```` + +In Guider, the programming language is shown top right of the codeblock. Hovering over a codeblock will show a copy button. + + +For syntax highlighting, we make use of [Shiki](https://shiki.style/guide/). You can find a list of [supported languages here](https://shiki.style/languages). + + + +## Inline code + +In the case where you want to display single line of code inside of a normal paragraph, instead of an entire code block. +You can use inline code blocks. + +Simply wrap `some text` in backticks (`) + +```md +Simply wrap `some text` in backticks (`) +``` + +To add syntax highlighting for a programming language to your inline codeblock. You can end your inline code with `{:LANGUAGE}{:txt}`. + +For example this line of javascript (js): `import hello from "world";{:js}`. + +```md +For example this line of javascript (js): `import hello from "world";{:js}`. +``` + + +## Titled code blocks + +You can add a title to a codeblock by simply adding the annotation `title="my-file.txt"`. The double quotes are required. + +```js title="index.js" +function hello() { + console.log("hello world"); +} +``` + +````md +```js title="index.js" +function hello() { + console.log("hello world"); +} +``` +```` + + +## Line numbers + +To add line numbers to your code block, add the attribute `showLineNumbers` to your code block. + +```js showLineNumbers +function test() { + console.log("hello world") +} +``` + +````md +```js showLineNumbers +function test() { + console.log("hello world") +} +``` +```` + + +## Highlight words + +To highlight specific words or phrases, add the `/xxx/` annotation to your code block. +```js /hello/ +function hello() { + console.log("hello world") +} +``` + +````md +```js /hello/ +function hello() { + console.log("hello world") +} +``` +```` + +In the case that you want to start highlighting at a specific point and not everything. You can add a comment with `[!code word:xxx]`. +If you want it to highlight multiple, you can specify an amount like so: `[!code word:xxx:3]` (it won't count on the line itself). + +```js +// [!code word:hello:2] +function hello() { + console.log("hello world"); + console.log("another hello world"); +} +``` + +````md +```js +// [\!code word:hello:2] +// make sure to remove the slash in this example before copying +function hello() { + console.log("hello world"); + console.log("another hello world"); +} +``` +```` + + +## Highlight lines + +At times, highlighting entire lines can be useful. There are a handful of choices here: +- `// [\!code --]` - mark line as removed +- `// [\!code ++]` - mark line as added +- `// [\!code highlight]` - highlight line +- `// [\!code error]` - show an error background on the line +- `// [\!code warning]` - show an warning background on the line + +You can add this at the end of any line of code in your code block to apply the style to the line. **Make sure to remove the slash from the examples**. + +```js + +console.log("Removed line"); // [!code --] + +console.log("Added line"); // [!code ++] + +console.log("Highlighted line"); // [!code highlight] + +console.log("Error on line"); // [!code error] + +console.log("Warning on line"); // [!code warning] + +``` + +If you want to apply line highlighting to multiple lines, you can also add it as an annotation `{1,3-5}`. This will apply to line 1 and the range 3 until 5 (inclusive) + +```js {1,3-5} +function hello() { + console.log("hello world"); + console.log("another hello world"); + + cool(); + return 42; +} +``` + +````md +```js {1,3-5} +function hello() { + console.log("hello world"); + console.log("another hello world"); + + cool(); + return 42; +} +``` +```` + + +## Focus lines + +When you have a bunch of code for completeness, but most of it is not relevant to the example. You have the option to focus only the lines you want. +Simply add `[!code focus]` in a comment at the end of your lines that you want to focus. + +```js +function hello() { + console.log("hello world"); // [!code focus] + console.log("another hello world"); // [!code focus] +} +``` + +````md +```js +// make sure to remove the slashes in this example before copying +function hello() { + console.log("hello world"); // [\!code focus] + console.log("another hello world"); // [\!code focus] +} +``` +```` + + +## NPM integration + +A nice little utility provided by The Guild called [`@theguild/remark-npm2yarn`](https://www.npmjs.com/package/@theguild/remark-npm2yarn) can +help you show your NPM install command in other package managers. + +```sh npm2yarn +npm install @neato/guider +``` + +````md +```sh npm2yarn +npm install @neato/guider +``` +```` + + +This only works with `npm install` commands, not any other subset of commands like `npx` or `npm run` + diff --git a/apps/docs/pages/docs/guider/writing/markdown/lists.mdx b/apps/docs/pages/docs/guider/writing/markdown/lists.mdx new file mode 100644 index 00000000..7dbc7043 --- /dev/null +++ b/apps/docs/pages/docs/guider/writing/markdown/lists.mdx @@ -0,0 +1,49 @@ +# Lists + +Lists in Markdown are very easy to write, they are essential in writing organised content. + +## Ordered list + +To write an ordered list, add a number with a dot after it followed by your text. +Note that you don't have to make the numbers be in order, Guider will make it be in order for you. + +1. Item one +2. Item two +3. Item three + +```md +1. Item one +2. Item two +3. Item three +``` + +## Unordered list + +To write an unordered list, add a dashes, followed by your text. Alternatively you can use any of these characters instead as prefix: `-`, `*`, `+` + +- Item one +- Item two +- Item three + +```md +- Item one +- Item two +- Item three +``` + +## Nesting lists + +To make lists indented, you add extra spaces or tabs into the nested lists. Just make sure that they align vertically and they will nest automatically. +- Item one +- Item two + - Item two/one + - Item two/two +- Item three + +```md +- Item one +- Item two + - Item two/one + - Item two/two +- Item three +``` diff --git a/apps/docs/pages/docs/guider/writing/markdown/making-pages.mdx b/apps/docs/pages/docs/guider/writing/markdown/making-pages.mdx new file mode 100644 index 00000000..f31eb69c --- /dev/null +++ b/apps/docs/pages/docs/guider/writing/markdown/making-pages.mdx @@ -0,0 +1,78 @@ +# Making pages + +On this page, you will learn how to write content pages in Guider. + + +## Create a new page + +Guider uses file system routing from Next.JS, this means the folder structure of in your `pages` directory +directly corresponds to the final URL of your page. + +A few examples: +- `/pages/hello/world.mdx` becomes `example.com/hello/world` +- `/pages/goodbye/moon/index.mdx` becomes `example.com/goodbye/moon` + + +You can use both `.md` and `.mdx` extension for your content files. + + + +## Linking your page to a theme + +In your theme file, you will have configured sites, directories and maybe layouts. If you only have one directory and site, +then there will be no need to link anything explicitly. + +If you have multiple sites or directories, you will need to specify which pages belong to which directory/site. +If unspecified, the first site and directory is chosen from your theme. + +You can choose a site/directory with a `_meta.json` file. +If you have a meta file inside of `/pages/hello/_meta.json` then it will apply to all pages starting with `/hello`. + +A example meta file: +```json title="/pages/hello/_meta.json" +{ + "site": "site-a", + "directory": "dir-a", + "layout": "default" +} +``` + +You can omit any field in this file and it will default to a upper level (like `/pages/_meta.json`) or just use the default. + +If you don't want to apply these settings to an entire directory but just a single page. You can also specify all options that are available in a meta file inside of the Frontmatter of the page: +```md +--- +site: "site-a" +directory: "dir-a" +layout: "default" +--- +# My heading +my paragraph +``` + +Just like the meta file, you can omit any field for it to default to an upper level. + +## Creating a page that doesn't use MDX or MD + +If you want to run other pages that aren't related to your documentation, you can simply make `.jsx` or `.tsx` files in the pages directory. + +It will be a completely blank page by default, if you want to still use the general layout of a site. You can use `{:tsx}` to make use of the standard layout. + +```tsx showLineNumbers +import { GuiderLayout } from '@neato/guider/client'; + +export default function MyPage() { + return ( + +

My page goes here

+ + ); +} +``` + + +## Writing in MD or MDX + +Guider uses most of [Github Flavoured Markdown](https://github.github.com/gfm/). If you are familiar with it, you can use everything you know. + +If you aren't familiar, you can refer to [Basic text](/docs/guider/writing/basic-text) to learn how to write in Markdown. diff --git a/apps/docs/pages/docs/guider/writing/test.mdx b/apps/docs/pages/docs/guider/writing/test.mdx deleted file mode 100644 index 599ca37a..00000000 --- a/apps/docs/pages/docs/guider/writing/test.mdx +++ /dev/null @@ -1,3 +0,0 @@ -# Welcome to Guider - -Nothing is here yet, check back later! diff --git a/apps/docs/pages/index.tsx b/apps/docs/pages/index.tsx index 9e1e6963..cbfb560a 100644 --- a/apps/docs/pages/index.tsx +++ b/apps/docs/pages/index.tsx @@ -1,39 +1,57 @@ -import { - Button, - Card, - CardGrid, - GuiderLayout, - Hero, -} from '@neato/guider/client'; +import { Button, GuiderLayout } from '@neato/guider/client'; +import { Home } from 'components/home'; +import { HomeCard, HomeCardContainer } from 'components/home-card'; + +interface Project { + href: string; + icon: string; + title: string; + description: string; +} export default function LandingPage() { + const projects: Project[] = [ + { + title: '@neato/guider', + description: 'Flexible documentation that looks good out of the box.', + href: '/docs/guider', + icon: 'mdi:cube-outline', + }, + { + title: '@neato/config', + description: + 'NodeJS configuration loader with strict typing and autocomplete.', + href: '/docs/config', + icon: 'mdi:cube-outline', + }, + ]; return ( - - - - Create your own new layouts - - Documentation that looks great out of the box - - Flexible but beautiful documentation, easy to write and easier to - extend. Exactly what you need everytime. - - - - - - - - - Effortlessly create beautiful documentation sites with just markdown. - - - Effortlessly create beautiful documentation sites with just markdown. - - - Effortlessly create beautiful documentation sites with just markdown. - - + + + + NeatoJS — A collection of JS tools that you will want. + + + Tools that follow the philosophy of doing only one thing, and doing it + right! + + + {projects.map((v) => ( + + View project + + } + > + {v.title} + {v.description} + + ))} + + ); } diff --git a/apps/docs/public/favicon.png b/apps/docs/public/favicon.png new file mode 100644 index 00000000..64ac36cc Binary files /dev/null and b/apps/docs/public/favicon.png differ diff --git a/apps/docs/public/logo.svg b/apps/docs/public/logo.svg new file mode 100644 index 00000000..1d05c9ef --- /dev/null +++ b/apps/docs/public/logo.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + diff --git a/apps/docs/theme.config.tsx b/apps/docs/theme.config.tsx index 8184d271..1d249e3a 100644 --- a/apps/docs/theme.config.tsx +++ b/apps/docs/theme.config.tsx @@ -1,26 +1,79 @@ -import { defineTheme, directory, group, link, site } from '@neato/guider/theme'; +import { + defineTheme, + directory, + group, + link, + site, + siteTemplate, + social, +} from '@neato/guider/theme'; +import { Logo } from 'components/logo'; -const template = site('template', { +const template = siteTemplate({ github: 'mrjvs/neatojs', dropdown: [link('Guider', '/docs/guider'), link('Config', '/docs/config')], + settings: { + colors: { + primary: '#A880FF', + primaryDarker: '#6C3DD0', + primaryLighter: '#D0BAFF', + }, + backgroundPattern: 'flare', + logo: () => , + }, + contentFooter: { + editRepositoryBase: 'https://github.com/mrjvs/neatojs/tree/dev/apps/docs', + socials: [ + social.discord('https://discord.gg/cGd5pKxWyK'), + social.github('https://github.com/mrjvs/neatojs'), + ], + }, + meta: { + titleTemplate: '%s - NeatoJS', + additionalLinkTags: [ + { + rel: 'icon', + href: '/favicon.png', + }, + ], + }, + logo: { + name: 'NeatoJS', + to: '/', + }, }); +const gdGuides = (url: string) => `/docs/guider/guides${url}`; +const gdWriting = (url: string) => `/docs/guider/writing${url}`; +const gdApi = (url: string) => `/docs/guider/api-reference${url}`; + const starLinks = [ - link('Github', '/docs/guider/docs/a', { + link('Github', 'https://github.com/mrjvs/neatojs', { style: 'star', + newTab: true, icon: 'akar-icons:github-fill', }), - link('Discord', '/docs/guider/docs/d', { + link('Discord', 'https://discord.gg/cGd5pKxWyK', { style: 'star', + newTab: true, icon: 'fa6-brands:discord', }), - link('Suggest features', '/docs/guider/docs/c', { + link('Suggest features', 'https://github.com/mrjvs/neatojs/issues', { style: 'star', + newTab: true, icon: 'streamline:chat-bubble-typing-oval-solid', }), ]; export default defineTheme([ + site('main', { + extends: [template], + directories: [ + directory('main', { + sidebar: [], + }), + ], + }), site('guider', { extends: [template], tabs: [ @@ -28,47 +81,68 @@ export default defineTheme([ link('Writing', '/docs/guider/writing'), link('API reference', '/docs/guider/api-reference'), ], - settings: { - backgroundPattern: 'flare', - }, directories: [ directory('guider-docs', { sidebar: [ ...starLinks, group('Getting started', [ - link('Installation', '/docs/guider/docs/test'), // making a new project - link('Setting up', '/docs/guider/docs'), // basic of configuring a project - link.nested('Migrating to Guider', [ - link('From Nextra', '/docs/guider/docs'), // nextra -> guider - link('From Docus', '/docs/guider/docs'), // docus -> guider - link('From Mintlify', '/docs/guider/docs'), // mintlify -> guider - ]), + link('Installation', gdGuides('/getting-started/installation'), { + icon: 'fa6-solid:download', + }), + link('Development', gdGuides('/getting-started/development'), { + icon: 'icon-park-solid:cpu', + }), + link.nested({ + title: 'Migrating to Guider', + icon: 'fa6-solid:sailboat', + items: [ + link( + 'From Nextra', + gdGuides('/getting-started/migration/from-nextra'), + ), + link( + 'From Docus', + gdGuides('/getting-started/migration/from-docus'), + ), + link( + 'From Mintlify', + gdGuides('/getting-started/migration/from-mintlify'), + ), + ], + }), ]), group('Configuration', [ - link('Colors & theme', '/docs/guider/docs'), - link('Redirects', '/docs/guider/docs'), - link('SEO & Meta tags', '/docs/guider/docs'), - link('Landing page', '/docs/guider/docs'), - link('Navigation', '/docs/guider/docs'), // changing tabs, dropdown, sidebar + link('Colors & theme', gdGuides('/config/theming')), + link('Redirects', gdGuides('/config/redirects')), + link('SEO & Meta tags', gdGuides('/config/seo')), + link('Landing page', gdGuides('/config/landing')), + link('Navigation', gdGuides('/config/navigation')), link.nested('Common setups', [ - link('Mutliple docs sites', '/docs/guider/docs'), - link('API reference + docs', '/docs/guider/docs'), - link('Blog posts + docs', '/docs/guider/docs'), + link( + 'Multiple docs sites', + gdGuides('/config/common/multi-docs'), + ), + link('API reference + docs', gdGuides('/config/common/api-ref')), + link('Blog posts + docs', gdGuides('/config/common/blog')), ]), - link('Examples', '/docs/guider/docs'), + link('Examples', gdGuides('/config/examples')), ]), group('Advanced', [ - link('Running multiple sites', '/docs/guider/docs'), // How to use _meta.json and multiple dirs/sites - link('Header', '/docs/guider/docs'), // Changing settings about header (just repo) - link('Footer', '/docs/guider/docs'), // Changing settings footer - link('Customising layout', '/docs/guider/docs'), // Custom partials - link('Deep-dive concepts', '/docs/guider/docs'), // Deep dive into directories, sites and layouts + link('Running multiple sites', gdGuides('/advanced/multi-site')), + link('Header', gdGuides('/advanced/header')), + link('Footer', gdGuides('/advanced/footer')), + link( + 'Customizing layout', + gdGuides('/advanced/customizing-layout'), + ), + link('Deep-dive concepts', gdGuides('/advanced/deep-dive')), ]), group('Deploying', [ - link('Github Pages', '/docs/guider/docs'), // deploy on github pages - link('Netlify', '/docs/guider/docs'), // Deploy on netlify - link('Vercel', '/docs/guider/docs'), // Deploy on Vercel - link('Cloudflare pages', '/docs/guider/docs'), // Deploy on CF pages + link('Github Pages', gdGuides('/deploy/github-pages')), + link('Netlify', gdGuides('/deploy/netlify')), + link('Vercel', gdGuides('/deploy/vercel')), + link('Cloudflare pages', gdGuides('/deploy/cloudflare')), + link('Docker', gdGuides('/deploy/docker')), ]), ], }), @@ -76,25 +150,54 @@ export default defineTheme([ sidebar: [ ...starLinks, group('Markdown', [ - link('Making pages', '/docs/guider/docs'), // How to make pages - link('Basic text', '/docs/guider/docs'), // Text & headings & inlines & links - link('Lists', '/docs/guider/docs'), // tables - link('Code blocks', '/docs/guider/docs'), // code blocks & npm2yarn + link('Making pages', gdWriting('/markdown/making-pages'), { + icon: 'fa6-solid:file-lines', + }), + link('Basic text', gdWriting('/markdown/basic-text'), { + icon: 'fa6-solid:font', + }), + link('Lists', gdWriting('/markdown/lists'), { + icon: 'fa6-solid:list-ul', + }), + link('Code blocks', gdWriting('/markdown/code-blocks'), { + icon: 'fa6-solid:code', + }), ]), group('Advanced markdown', [ - link('Tables', '/docs/guider/docs'), // Making tables - link('Quotes', '/docs/guider/docs'), // quotes - link('Footnotes', '/docs/guider/docs'), // footnotes - link('Dividers', '/docs/guider/docs'), // dividers + link('Tables', gdWriting('/advanced/tables'), { + icon: 'fa6-solid:table', + }), + link('Quotes', gdWriting('/advanced/quotes'), { + icon: 'fa6-solid:quote-left', + }), + link('Footnotes', gdWriting('/advanced/footnotes'), { + icon: 'fa6-solid:note-sticky', + }), + link('Dividers', gdWriting('/advanced/dividers'), { + icon: 'fa6-solid:grip-lines', + }), ]), group('Components', [ - link('Code groups', '/docs/guider/docs'), // - link('Callouts', '/docs/guider/docs'), // - link('Frames', '/docs/guider/docs'), // - link('Custom components', '/docs/guider/docs'), // making custom components + link('Code groups', gdWriting('/components/code-groups'), { + icon: 'fa6-solid:layer-group', + }), + link('Callouts', gdWriting('/components/callouts'), { + icon: 'fa6-solid:bell-concierge', + }), + link('Tabs', gdWriting('/components/tabs'), { + icon: 'fa6-solid:window-restore', + }), + link('Steps', gdWriting('/components/steps'), { + icon: 'fa6-solid:list-ol', + }), + link('Frames', gdWriting('/components/frames'), { + icon: 'fa6-solid:image', + }), + link('Custom components', gdWriting('/components/custom'), { + icon: 'fa6-solid:boxes-stacked', + }), ]), ], }), @@ -102,31 +205,34 @@ export default defineTheme([ sidebar: [ ...starLinks, group('Theme configuration', [ - link('defineTheme()', '/docs/guider/docs'), - link('site()', '/docs/guider/docs'), - link('directory()', '/docs/guider/docs'), - link('link()', '/docs/guider/docs'), - link('group()', '/docs/guider/docs'), - link('seperator()', '/docs/guider/docs'), - link('component()', '/docs/guider/docs'), + link('defineTheme()', gdApi('/theme/define-theme')), + link('site()', gdApi('/theme/site')), + link('directory()', gdApi('/theme/directory')), + link('link()', gdApi('/theme/link')), + link('group()', gdApi('/theme/group')), + link('seperator()', gdApi('/theme/seperator')), + link('component()', gdApi('/theme/component')), ]), group('_meta.json', [ - link('Structure of _meta.json', '/docs/guider/docs'), + link('Structure of _meta.json', gdApi('/meta/structure')), ]), group('Client functions', [ - link('createRedirect()', '/docs/guider/docs'), - link('createNotFoundPage()', '/docs/guider/docs'), - link('useGuider()', '/docs/guider/docs'), - link('useGuiderPage()', '/docs/guider/docs'), + link('createRedirect()', gdApi('/functions/create-redirect')), + link( + 'createNotFoundPage()', + gdApi('/functions/create-not-found-page'), + ), + link('useGuider()', gdApi('/functions/use-guider')), + link('useGuiderPage()', gdApi('/functions/use-guider-page')), ]), group('Theme components', [ - link('', '/docs/guider/docs'), - link('', '/docs/guider/docs'), - link('', '/docs/guider/docs'), - link('', '/docs/guider/docs'), + link('', gdApi('/components/guider-header')), + link('', gdApi('/components/guider-layout')), + link('', gdApi('/components/guider-sidebar')), + link('', gdApi('/components/guider-toc')), ]), ], }), @@ -137,6 +243,7 @@ export default defineTheme([ directories: [ directory('main', { sidebar: [ + ...starLinks, group('Guide', [ link('Why use @neato/config', '/docs/config/guide/why-neat-config'), link('Installation', '/docs/config/guide/installation'), diff --git a/examples/guider/kitchen-sink/package.json b/examples/guider/kitchen-sink/package.json index 9a7001c1..0f4ed745 100644 --- a/examples/guider/kitchen-sink/package.json +++ b/examples/guider/kitchen-sink/package.json @@ -1,6 +1,6 @@ { - "name": "docs", - "description": "Documentation for neatojs", + "name": "@repo/examples-guider-kitchen-sink", + "description": "@neato/guider kitchen sink", "private": true, "version": "0.0.0", "eslintConfig": { diff --git a/examples/guider/kitchen-sink/pages/_app.tsx b/examples/guider/kitchen-sink/pages/_app.tsx index 03463a97..b77d1e9d 100644 --- a/examples/guider/kitchen-sink/pages/_app.tsx +++ b/examples/guider/kitchen-sink/pages/_app.tsx @@ -1,6 +1,4 @@ -import type { AppProps } from 'next/app'; import '@neato/guider/style.css'; +import { createGuiderApp } from '@neato/guider/client'; -export default function MyApp({ Component, pageProps }: AppProps) { - return ; -} +export default createGuiderApp(); diff --git a/examples/guider/kitchen-sink/pages/docs/guides/index.mdx b/examples/guider/kitchen-sink/pages/docs/guides/index.mdx index 247fcc66..3d31cbb8 100644 --- a/examples/guider/kitchen-sink/pages/docs/guides/index.mdx +++ b/examples/guider/kitchen-sink/pages/docs/guides/index.mdx @@ -23,3 +23,69 @@ Open an issue to report bugs or to propose new features. - **Reporting bugs**: describe the bug as clearly as you can, including steps to reproduce, what happened and what you were expecting to happen. Also include browser version, OS and other related software's (npm, Node.js, etc) versions when applicable. - **Reporting bugs**: describe the bug as clearly as you can, including steps to reproduce, what happened and what you were expecting to happen. Also include browser version, OS and other related software's (npm, Node.js, etc) versions when applicable. + + + + ```ts + console.log("hello world"); + ``` + + + ```ts + console.log("hello world"); + ``` + + + ```ts + console.log("hello world"); + ``` + + + ```ts + console.log("hello world"); + ``` + + + ```ts + console.log("hello world"); + ``` + + + ```ts + console.log("hello world"); + ``` + + + + + + ```ts + console.log("hello world"); + ``` + + + ```ts + console.log("hello world"); + ``` + + + ```ts + console.log("hello world"); + ``` + + + ```ts + console.log("hello world"); + ``` + + + ```ts + console.log("hello world"); + ``` + + + ```ts + console.log("hello world"); + ``` + + diff --git a/examples/guider/kitchen-sink/theme.config.tsx b/examples/guider/kitchen-sink/theme.config.tsx index ae42bc18..49caf621 100644 --- a/examples/guider/kitchen-sink/theme.config.tsx +++ b/examples/guider/kitchen-sink/theme.config.tsx @@ -14,6 +14,8 @@ const siteTemplate = site('docs', { link('API reference', '/api-ref'), ], navigation: [ + link('Documentation', '/docs/guides', { icon: 'fa6-solid:house' }), + link('API reference', '/api-ref'), link('Documentation', '/docs/guides', { icon: 'fa6-solid:house' }), link('API reference', '/api-ref'), seperator(), @@ -28,8 +30,7 @@ export default defineTheme([ contentFooter: { socials: [], text: 'Copyright (c) 2023', - editRepositoryBase: - 'https://github.com/mrjvs/neatojs/examples/guider/kitchen-sink', + editRepositoryBase: 'https://github.com/mrjvs/neatojs', }, pageFooter: { text: 'Made with love <3', diff --git a/examples/guider/minimal/pages/_app.tsx b/examples/guider/minimal/pages/_app.tsx index a8942591..b77d1e9d 100644 --- a/examples/guider/minimal/pages/_app.tsx +++ b/examples/guider/minimal/pages/_app.tsx @@ -1,6 +1,4 @@ -import type { AppProps } from 'next/app'; import '@neato/guider/style.css'; +import { createGuiderApp } from '@neato/guider/client'; -export default function GuiderApp({ Component, pageProps }: AppProps) { - return ; -} +export default createGuiderApp(); diff --git a/examples/guider/minimal/theme.config.tsx b/examples/guider/minimal/theme.config.tsx index 02c8a7c8..0b52ceaa 100644 --- a/examples/guider/minimal/theme.config.tsx +++ b/examples/guider/minimal/theme.config.tsx @@ -1,11 +1,9 @@ import { defineTheme, directory, link } from '@neato/guider/theme'; export default defineTheme({ - id: "main", directories: [ - directory({ - id: "main", - sidebarItems: [ + directory('main', { + sidebar: [ link("Home", "/") ] }) diff --git a/packages/guider/README.md b/packages/guider/README.md index 71a48dec..dc77e9f9 100644 --- a/packages/guider/README.md +++ b/packages/guider/README.md @@ -1,56 +1,33 @@ -# @neato/guider +# ⚡@neato/guider -Documentation site generator. +Beautiful documentation sites, without all the hassle. Check out the documentation -## Features -- Easy to write in, its just markdown -- Use react components in your markdown through MDX, with support for global components. -- customizable layouts, use layouts both in mdx files and outside -- Multiple documentations in one Next.JS app -## How to use it? -1. Make a Next.JS app: https://nextjs.org/docs/getting-started/installation -2. Install guider: `npm i next @neato/guider` -3. Put this in `next.config.js`: -```js -const { guider } = require('@neato/guider'); +## 🔥Features +- Beautiful default theme. +- Use React components inside your markdown, through MDX. +- Run as many documentation sites as you want with just one deployment. +- Based on NextJS, so not restricted to just documentation. +- Customize every part of the layout, possible on a per page basis. -const withGuider = guider({ - themeConfig: './theme.config.tsx', -}); -module.exports = withGuider(); -``` -4. Create a file `theme.config.tsx` and put this in it: -```ts -import { defineTheme, link } from '@neato/guider/theme'; - -export default defineTheme({ - id: "main" - directories: [ - { - id: "main" - sidebarItems: { - link('Page A', '/a'), - link('Page B', '/b'), - }, - }, - ], -}); -``` -5. Make a `pages/_app.ts` file and put this in it: -```ts -import type { AppProps } from 'next/app'; -import '@neato/guider/style.css'; - -export default function MyApp({ Component, pageProps }: AppProps) { - return ; -} -``` -6. Make your first page by creating a new file `pages/index.mdx`, and put this in it: -```md -# Hello world +## 🍄Installation / usage + +> [TIP] +> **Visit the [documentation](https://neatojs.com/docs/guider/guides/installation) on how to install. + + +## 📖Documentation + +**Visit the [website](https://neatojs.com/docs/guider) for documentation. + + +## 🧬 Running locally for development + +```sh +npm i -g pnpm # install PNPM if you don't have it already +pnpm i # install dependencies of the entire repo -Welcome to Guider! +pnpm -C packages/guider run dev # run library dev script in directory +pnpm -C apps/docs run dev # run documentation site dev script in directory ``` -7. You're all set. Have fun making docs! diff --git a/packages/guider/package.json b/packages/guider/package.json index ab47f446..27cc3412 100644 --- a/packages/guider/package.json +++ b/packages/guider/package.json @@ -1,8 +1,23 @@ { "name": "@neato/guider", - "version": "0.0.1", - "description": "Documentation site generator framework based on Next.js", + "version": "0.1.0", + "description": "Beautiful documentation sites, without all the hassle", "main": "./dist/index.js", + "homepage": "https://neatojs.com/docs/guider", + "repository": "https://github.com/mrjvs/neatojs", + "bugs": { + "url": "https://github.com/mrjvs/neatojs/issues" + }, + "engines": { + "node": ">=20" + }, + "keywords": [ + "mdx", + "documentation", + "nextjs", + "markdown" + ], + "license": "MIT", "files": [ "dist/**", "style.css", @@ -69,6 +84,7 @@ "@repo/typescript-config": "workspace:*", "@types/color": "^3.0.6", "@types/extra-watch-webpack-plugin": "^1.0.6", + "@types/git-url-parse": "^9.0.3", "@types/react": "18.2.56", "@types/webpack": "^5.28.5", "autoprefixer": "^10.4.17", @@ -93,6 +109,7 @@ "classnames": "^2.5.1", "color": "^4.2.3", "extra-watch-webpack-plugin": "^1.0.3", + "git-url-parse": "^14.0.0", "glob": "^10.3.10", "gray-matter": "^4.0.3", "next-seo": "^6.5.0", @@ -102,6 +119,7 @@ "remark-frontmatter": "^5.0.0", "remark-gfm": "^4.0.0", "remark-heading-id": "^1.0.1", + "remark-link-rewrite": "^1.0.7", "shiki": "^1.1.7", "tailwindcss-themer": "^4.0.0", "type-fest": "^4.10.3", diff --git a/packages/guider/src/client/components/github.tsx b/packages/guider/src/client/components/github.tsx index c6cf9971..7bfae263 100644 --- a/packages/guider/src/client/components/github.tsx +++ b/packages/guider/src/client/components/github.tsx @@ -25,13 +25,13 @@ export function GithubDisplay(props: GithubDisplayProps) {

{name}

- + {stats ? approx(stats.stars) : '-'} - + {stats ? approx(stats.forks) : '-'} diff --git a/packages/guider/src/client/components/head.tsx b/packages/guider/src/client/components/head.tsx index 4dfc57cc..c794d455 100644 --- a/packages/guider/src/client/components/head.tsx +++ b/packages/guider/src/client/components/head.tsx @@ -1,23 +1,36 @@ -import { DefaultSeo, NextSeo } from 'next-seo'; +import { NextSeo } from 'next-seo'; import type { MetaTagComponent } from '../../theme'; import { useGuiderPage } from '../hooks/use-guider-page'; -export function GuiderMetaComponent(props: { meta: MetaTagComponent }) { - if (typeof props.meta === 'function') return props.meta(); +type PageMeta = { + title?: string; + description?: string; +}; - return ; +export function GuiderMetaComponent(props: { + meta: MetaTagComponent; + pageMeta: PageMeta; +}) { + if (typeof props.meta === 'function') return props.meta(props.pageMeta); + + return ( + + ); } export function GuiderMeta() { const { page, site } = useGuiderPage(); - const title = page?.meta?.title ?? page?.headings[0]?.value; - const desc = page?.meta?.description ?? page?.excerpt; + const pageMeta = { + title: page?.meta?.title ?? page?.headings[0]?.value, + description: page?.meta?.description ?? page?.excerpt, + }; return ( - <> - - {site.meta ? : null} - + ); } diff --git a/packages/guider/src/client/components/icon.tsx b/packages/guider/src/client/components/icon.tsx index 75d0368f..0b3a56ed 100644 --- a/packages/guider/src/client/components/icon.tsx +++ b/packages/guider/src/client/components/icon.tsx @@ -1,15 +1,20 @@ import { Icon as IconifyIcon } from '@iconify-icon/react'; import classNames from 'classnames'; -export function Icon(props: { icon: string; className?: string }) { +export function Icon(props: { + icon: string; + className?: string; + inline?: boolean; +}) { return ( - + ); } diff --git a/packages/guider/src/client/components/markdown/footnotes.tsx b/packages/guider/src/client/components/markdown/footnotes.tsx index 1703ca14..791b630b 100644 --- a/packages/guider/src/client/components/markdown/footnotes.tsx +++ b/packages/guider/src/client/components/markdown/footnotes.tsx @@ -18,6 +18,7 @@ export function MarkdownFootnoteLink(props: MarkdownProps) { className="gd-text-primary gd-translate-y-1 gd-inline-block gd-no-underline gd-font-bold hover:gd-text-primaryDark gd-transition-colors gd-duration-100" > diff --git a/packages/guider/src/client/components/markdown/headings.tsx b/packages/guider/src/client/components/markdown/headings.tsx index 2b2eb6e2..16691faa 100644 --- a/packages/guider/src/client/components/markdown/headings.tsx +++ b/packages/guider/src/client/components/markdown/headings.tsx @@ -1,14 +1,14 @@ import classNames from 'classnames'; import type { ElementProps, MarkdownProps } from './types'; -const headingClasses = 'gd-relative gd-group'; +const headingClasses = 'gd-relative gd-group gd-scroll-m-48'; function HeadingAnchor(props: { attrs: ElementProps }) { if (!props.attrs.id) return null; return ( # diff --git a/packages/guider/src/client/components/markdown/inline.tsx b/packages/guider/src/client/components/markdown/inline.tsx index 43ddcef2..894f32a8 100644 --- a/packages/guider/src/client/components/markdown/inline.tsx +++ b/packages/guider/src/client/components/markdown/inline.tsx @@ -6,7 +6,7 @@ export function MarkdownStrong(props: MarkdownProps) { diff --git a/packages/guider/src/client/components/markdown/paragraph.tsx b/packages/guider/src/client/components/markdown/paragraph.tsx index 64c678dd..19648f85 100644 --- a/packages/guider/src/client/components/markdown/paragraph.tsx +++ b/packages/guider/src/client/components/markdown/paragraph.tsx @@ -1,4 +1,5 @@ import type { ReactNode } from 'react'; +import Link from 'next/link'; import type { ElementProps, MarkdownProps } from './types'; export type MarkdownParagraphProps = { @@ -16,11 +17,12 @@ export function MarkdownParagraph(props: MarkdownParagraphProps) { export function MarkdownLink(props: MarkdownProps) { return ( - {props.children} - + ); } diff --git a/packages/guider/src/client/components/public/code-group.tsx b/packages/guider/src/client/components/public/code-group.tsx index d4de02a5..f78b292a 100644 --- a/packages/guider/src/client/components/public/code-group.tsx +++ b/packages/guider/src/client/components/public/code-group.tsx @@ -57,22 +57,24 @@ const CodeGroupContainer = (props: CodeGroupProps) => { return (

- - {tabs.map((v) => ( - - {({ selected }) => ( -
- {v} -
- )} - - ))} + +
+ {tabs.map((v) => ( + + {({ selected }) => ( +
+ {v} +
+ )} + + ))} +
{props.children} diff --git a/packages/guider/src/client/components/public/tabs.tsx b/packages/guider/src/client/components/public/tabs.tsx index 2b887db6..19bedd53 100644 --- a/packages/guider/src/client/components/public/tabs.tsx +++ b/packages/guider/src/client/components/public/tabs.tsx @@ -26,22 +26,27 @@ const TabsContainer = (props: TabsProps) => { ); return ( - - {props.items.map((v) => ( - - {({ selected }) => ( -
- {v} -
- )} - - ))} + +
+
+
+ {props.items.map((v) => ( + + {({ selected }) => ( +
+ {v} +
+ )} + + ))} +
+
{props.children} diff --git a/packages/guider/src/client/hooks/use-guider-filepath.tsx b/packages/guider/src/client/hooks/use-guider-filepath.tsx new file mode 100644 index 00000000..00543a4d --- /dev/null +++ b/packages/guider/src/client/hooks/use-guider-filepath.tsx @@ -0,0 +1,21 @@ +import { useRouter } from 'next/router'; +import { useMemo } from 'react'; +import type { PageMapItem } from '../../theme'; +import { pageMap } from '../virtuals'; + +export function getFilePath(pageUrl: string): PageMapItem | null { + const matches = pageMap.filter((v) => pageUrl === v.sitePath); + const match: PageMapItem | undefined = matches[0]; + return match ?? null; +} + +export function useGuiderFilePath() { + const router = useRouter(); + const pageUrl = router.pathname; + + const filePath = useMemo(() => { + return getFilePath(pageUrl); + }, [pageUrl, pageMap]); + + return filePath; +} diff --git a/packages/guider/src/client/hooks/use-guider.tsx b/packages/guider/src/client/hooks/use-guider.tsx index 3b03ef88..01733b0c 100644 --- a/packages/guider/src/client/hooks/use-guider.tsx +++ b/packages/guider/src/client/hooks/use-guider.tsx @@ -1,14 +1,14 @@ import { useMemo } from 'react'; import { useRouter } from 'next/router'; -import type { MetaConf, PageMapItem } from '../../theme'; +import type { MetaConf, MetaMapItem } from '../../theme'; import { mergeLayoutSettings } from '../../theme/components/layout'; -import { sites, pageMap } from '../virtuals'; +import { sites, metaMap } from '../virtuals'; export function getPage(pageUrl: string) { - const matches = pageMap + const matches = metaMap .filter((v) => pageUrl.startsWith(v.sitePath)) .sort((a, b) => b.sitePath.length - a.sitePath.length); - const match: PageMapItem | undefined = matches[0]; + const match: MetaMapItem | undefined = matches[0]; return match ?? null; } @@ -30,7 +30,7 @@ export function getGuiderContext(pageUrl: string, pageMeta: MetaConf = {}) { const settings = mergeLayoutSettings(layout.settings, dir.settings); return { - pageMap, + metaMap, settings, directory: dir, layout, diff --git a/packages/guider/src/client/hooks/use-toc.ts b/packages/guider/src/client/hooks/use-toc.ts index 4341a097..c7ae6d9f 100644 --- a/packages/guider/src/client/hooks/use-toc.ts +++ b/packages/guider/src/client/hooks/use-toc.ts @@ -1,5 +1,45 @@ import { useCallback, useEffect, useState } from 'react'; +export function useVisibleIds(contentId: string, ids: string[]) { + const [finalList, setFinalList] = useState(ids); + + const check = useCallback( + (idList: string[]) => { + const newList: string[] = []; + idList.forEach((id) => { + const el = document.getElementById(id); + if (!el) return; + if (el.offsetParent === null) return; + newList.push(id); + }); + setFinalList(newList); + }, + [ids], + ); + + useEffect(() => { + const targetNode = document.getElementById(contentId); + if (!targetNode) return; + + const observer = new MutationObserver(() => { + check(ids); + }); + + observer.observe(targetNode, { + childList: true, + subtree: true, + }); + + check(ids); + + return () => { + observer.disconnect(); + }; + }, [contentId, check, JSON.stringify(ids)]); + + return finalList; +} + export function useToc(ids: string[]) { const [activeId, setActiveId] = useState(null); @@ -47,7 +87,7 @@ export function useToc(ids: string[]) { if (!el) return null; const y = el.getBoundingClientRect().top + window.scrollY; window.scrollTo({ - top: y - 120, + top: y - 180, behavior: 'smooth', }); }, []); diff --git a/packages/guider/src/client/index.ts b/packages/guider/src/client/index.ts index 80d19ec5..5f75e6f8 100644 --- a/packages/guider/src/client/index.ts +++ b/packages/guider/src/client/index.ts @@ -1,6 +1,7 @@ export * from './virtuals'; export * from './page/create-mdx-page'; +export * from './page/create-guider-app'; export * from './page/create-404-page'; export * from './page/redirect'; export * from './hooks/use-guider-page'; @@ -9,4 +10,5 @@ export * from './hooks/use-toc'; export * from './partials/index'; export * from './components/public'; +export * from './components/icon'; export { useMDXComponents } from './components/markdown'; diff --git a/packages/guider/src/client/page/create-404-page.tsx b/packages/guider/src/client/page/create-404-page.tsx index 48a6084f..46824cae 100644 --- a/packages/guider/src/client/page/create-404-page.tsx +++ b/packages/guider/src/client/page/create-404-page.tsx @@ -8,7 +8,7 @@ export type CreateNotFoundPage = { export function createNotFoundPage(opts?: CreateNotFoundPage) { const content = ( -
+

diff --git a/packages/guider/src/client/page/create-guider-app.tsx b/packages/guider/src/client/page/create-guider-app.tsx new file mode 100644 index 00000000..ff719fe7 --- /dev/null +++ b/packages/guider/src/client/page/create-guider-app.tsx @@ -0,0 +1,15 @@ +import type { NextComponentType } from 'next'; +import type { AppProps } from 'next/app'; +import type { ReactElement, ReactNode } from 'react'; + +export type GuiderPageWithLayout = NextComponentType & { + getLayout?: (content: ReactElement) => ReactNode; +}; + +export function createGuiderApp(): (props: AppProps) => ReactNode { + return function GuiderApp(props: AppProps) { + const Comp = props.Component as GuiderPageWithLayout; + const getLayout = Comp.getLayout ?? ((page) => page); + return getLayout(); + }; +} diff --git a/packages/guider/src/client/page/create-mdx-page.tsx b/packages/guider/src/client/page/create-mdx-page.tsx index bc28d469..c0f2d9f7 100644 --- a/packages/guider/src/client/page/create-mdx-page.tsx +++ b/packages/guider/src/client/page/create-mdx-page.tsx @@ -1,5 +1,6 @@ import { GuiderLayout } from '../partials/layout'; import * as components from '../components/public'; +import type { GuiderPageWithLayout } from './create-guider-app'; import type { MdxHeadings } from './context'; import type { PageMeta } from './types'; @@ -14,13 +15,19 @@ export type CreateMdxPageOptions = { export function createMdxPage(opts: CreateMdxPageOptions) { const Content = opts.MDXContent; - return () => ( - - - + const page: GuiderPageWithLayout = () => ( + ); + page.getLayout = (content) => { + return ( + + {content} + + ); + }; + return page; } diff --git a/packages/guider/src/client/partials/content-footer/content-footer.tsx b/packages/guider/src/client/partials/content-footer/content-footer.tsx index 70048965..f3403a92 100644 --- a/packages/guider/src/client/partials/content-footer/content-footer.tsx +++ b/packages/guider/src/client/partials/content-footer/content-footer.tsx @@ -1,51 +1,57 @@ +import Link from 'next/link'; import { Icon } from '../../components/icon'; +import { useGuiderPage } from '../../hooks/use-guider-page'; +import type { SocialTypes } from '../../../theme/components/social'; +import { GithubEditLink, useEditLink } from './github-edit-link'; + +const iconMap: Record = { + discord: 'ic:twotone-discord', + github: 'mdi:github', + slack: 'mdi:slack', + mastodon: 'fa6-brands:mastodon', + twitter: 'fa6-brands:x-twitter', +}; + +function FooterSocial(props: { icon: string; url: string }) { + return ( + + + + ); +} export function ContentFooterInternal() { const year = new Date().getFullYear(); + const { site } = useGuiderPage(); + const editUrl = useEditLink(site?.contentFooter?.editRepositoryBase); + const copyright = <>Copyright © {year}; + const socials = site.contentFooter?.socials ?? []; + return ( -