Skip to content

Commit

Permalink
Merge pull request #396 from vordgi/rd-395
Browse files Browse the repository at this point in the history 
rd-395 refactor utils
  • Loading branch information
@vordgi
vordgi authored Nov 16, 2024
2 parents 4c5fd0e + e78672f commit 406d474
Show file tree
Hide file tree
Showing 33 changed files with 400 additions and 357 deletions.
4 changes: 2 additions & 2 deletions docs/01-getting-started/03-initialization.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,12 @@ To use Robindoc with all its features, you need to initialize it. To do this, yo

## Calling the Method

The method will return dynamic components [`Page`](../03-customization/01-elements/page.md) and [`Sidebar`](../03-customization/01-elements/sidebar.md), as well as the methods [`getPages`](../03-customization/02-tools/get-pages.md), [`getMeta`](../03-customization/02-tools/get-meta.md), and [`getPageContent`](../03-customization/02-tools/get-page-content.md).
The method will return dynamic components [`Page`](../03-customization/01-elements/page.md) and [`Sidebar`](../03-customization/01-elements/sidebar.md), as well as the methods [`getStaticParams`](../03-customization/02-tools/get-static-params.md), [`getMetadata`](../03-customization/02-tools/get-metadata.md), and [`getPageData`](../03-customization/02-tools/get-page-data.md).

```tsx filename="app/docs/robindoc.ts" tab="TypeScript" switcher clone="jsx|JavaScript|app/docs/robindoc.js"
import { initializeRobindoc } from "robindoc";

export const { Page, Sidebar, getPages, getMeta, getPageContent } =
export const { Page, Sidebar, getStaticParams, getMetadata, getPageData } =
initializeRobindoc({
configuration: {
sourceRoot: "../docs",
Expand Down
120 changes: 60 additions & 60 deletions docs/01-getting-started/04-app-organization.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ However, when using the automatic mode for generating the structure, the documen

You can initialize Robindoc on any subpath of your site, as long as you specify the [`basePath`](../02-structure/01-configuration.md) in the project initialization and pass the correct path in the Robindoc components.

After initialization, you will receive Sidebar, Page, getPages, getMeta, and getPageContent. Read more on the [Initialization](../03-initialization.md) page.
After initialization, you will receive Sidebar, Page, getStaticParams, getMetadata, and getPageData. Read more on the [Initialization](../03-initialization.md) page.

Global elements - [`RobinProvider`](../03-customization/01-elements/robin-provider.md), [`Header`](../03-customization/01-elements/header.md), [`Footer`](../03-customization/01-elements/footer.md), [`Containers`](../03-customization/01-elements/containers.md) and [`Sidebar`](../03-customization/01-elements/sidebar.md) - should ideally be placed above all pages and reused across all.
Currently, Robindoc works only with the App Router. Once RSC is available for the Pages Router, Robindoc will automatically support it as well.
Expand All @@ -28,49 +28,49 @@ Currently, Robindoc works only with the App Router. Once RSC is available for th

Next.js supports dynamic routes, so it is recommended to set up one [dynamic segment](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes#optional-catch-all-segments) for all documentation pages.

```tsx filename="app/docs/[[...path]]/page.tsx" switcher tab="v14 TSX"
import { Page, Sidebar, getMeta, getPages } from "../robindoc";
```tsx filename="app/docs/[[...segments]]/page.tsx" switcher tab="v14 TSX"
import { Page, Sidebar, getMetadata, getStaticParams } from "../robindoc";

const Page: React.FC<{ params }: { params: { path?: string[] } }> = async ({ params }) => {
const pathname = "/docs/" + (params.path?.join("/") || "");
const Page: React.FC<{ params }: { params: { segments?: string[] } }> = async ({ params }) => {
const pathname = "/docs/" + (params.segments?.join("/") || "");

return <Page pathname={pathname} />;
};

export default Page;
```

```jsx filename="app/docs/[[...path]]/page.js" switcher tab="v14 JSX"
import { Page, Sidebar, getMeta, getPages } from "../robindoc";
```jsx filename="app/docs/[[...segments]]/page.js" switcher tab="v14 JSX"
import { Page, Sidebar, getMetadata, getStaticParams } from "../robindoc";

const Page = async ({ params }) => {
const pathname = "/docs/" + (params.path?.join("/") || "");
const pathname = "/docs/" + (params.segments?.join("/") || "");

return <Page pathname={pathname} />;
};

export default Page;
```
```tsx filename="app/docs/[[...path]]/page.tsx" switcher tab="v15 TSX"
import { Page, Sidebar, getMeta, getPages } from "../robindoc";
```tsx filename="app/docs/[[...segments]]/page.tsx" switcher tab="v15 TSX"
import { Page, Sidebar, getMetadata, getStaticParams } from "../robindoc";

const Page: React.FC<{ params }: { params: Promise<{ path?: string[] }> }> = async ({ params }) => {
const { path } = await params;
const pathname = "/docs/" + (path?.join("/") || "");
const Page: React.FC<{ params }: { params: Promise<{ segments?: string[] }> }> = async ({ params }) => {
const { segments } = await params;
const pathname = "/docs/" + (segments?.join("/") || "");

return <Page pathname={pathname} />;
};

export default Page;
```
```jsx filename="app/docs/[[...path]]/page.js" switcher tab="v15 JSX"
import { Page, Sidebar, getMeta, getPages } from "../robindoc";
```jsx filename="app/docs/[[...segments]]/page.js" switcher tab="v15 JSX"
import { Page, Sidebar, getMetadata, getStaticParams } from "../robindoc";

const Page = async ({ params }) => {
const { path } = await params;
const pathname = "/docs/" + (path?.join("/") || "");
const { segments } = await params;
const pathname = "/docs/" + (segments?.join("/") || "");

return <Page pathname={pathname} />;
};
Expand All @@ -82,85 +82,85 @@ For more details about the props, refer to the [`Page`](../03-customization/01-e
You should also set up metadata generation and static parameters generation (if you want to use SSG, which is highly recommended):
```tsx filename="app/docs/[[...path]]/page.tsx" switcher tab="v14 TSX"
import { Page, Sidebar, getMeta, getPages } from "../robindoc";
```tsx filename="app/docs/[[...segments]]/page.tsx" switcher tab="v14 TSX"
import { Page, Sidebar, getMetadata, getStaticParams } from "../robindoc";

// ...

export const generateMetadata = async ({
params,
}: {
params: { path?: string[] };
params: { segments?: string[] };
}) => {
const pathname = "/docs/" + (params.path?.join("/") || "");
const meta = await getMeta(pathname);
const pathname = "/docs/" + (params.segments?.join("/") || "");
const metadata = await getMetadata(pathname);

return meta;
return metadata;
};

export const generateStaticParams = async () => {
const pages = await getPages("/docs/");
return pages.map((page) => ({ path: page.split("/").slice(2) }));
const staticParams = await getStaticParams("/docs/");
return staticParams;
};
```
```jsx filename="app/docs/[[...path]]/page.js" switcher tab="v14 JSX"
import { Page, Sidebar, getMeta, getPages } from "../robindoc";
```jsx filename="app/docs/[[...segments]]/page.js" switcher tab="v14 JSX"
import { Page, Sidebar, getMetadata, getStaticParams } from "../robindoc";

// ...

export const generateMetadata = async ({ params }) => {
const pathname = "/docs/" + (params.path?.join("/") || "");
const meta = await getMeta(pathname);
const pathname = "/docs/" + (params.segments?.join("/") || "");
const metadata = await getMetadata(pathname);

return meta;
return metadata;
};

export const generateStaticParams = async () => {
const pages = await getPages("/docs/");
return pages.map((page) => ({ path: page.split("/").slice(2) }));
const staticParams = await getStaticParams("/docs/");
return staticParams;
};
```
```tsx filename="app/docs/[[...path]]/page.tsx" switcher tab="v15 TSX"
import { Page, Sidebar, getMeta, getPages } from "../robindoc";
```tsx filename="app/docs/[[...segments]]/page.tsx" switcher tab="v15 TSX"
import { Page, Sidebar, getMetadata, getStaticParams } from "../robindoc";

// ...

export const generateMetadata = async ({
params,
}: {
params: Promise<{ path?: string[] }>;
params: Promise<{ segments?: string[] }>;
}) => {
const { path } = await params;
const pathname = "/docs/" + (path?.join("/") || "");
const meta = await getMeta(pathname);
const { segments } = await params;
const pathname = "/docs/" + (segments?.join("/") || "");
const metadata = await getMetadata(pathname);

return meta;
return metadata;
};

export const generateStaticParams = async () => {
const pages = await getPages("/docs/");
return pages.map((page) => ({ path: page.split("/").slice(2) }));
const staticParams = await getStaticParams("/docs/");
return staticParams;
};
```
```jsx filename="app/docs/[[...path]]/page.js" switcher tab="v15 JSX"
import { Page, Sidebar, getMeta, getPages } from "../robindoc";
```jsx filename="app/docs/[[...segments]]/page.js" switcher tab="v15 JSX"
import { Page, Sidebar, getMetadata, getStaticParams } from "../robindoc";

// ...

export const generateMetadata = async ({ params }) => {
const { path } = await params;
const pathname = "/docs/" + (path?.join("/") || "");
const meta = await getMeta(pathname);
const { segments } = await params;
const pathname = "/docs/" + (segments?.join("/") || "");
const metadata = await getMetadata(pathname);

return meta;
return metadata;
};

export const generateStaticParams = async () => {
const pages = await getPages("/docs/");
return pages.map((page) => ({ path: page.split("/").slice(2) }));
const staticParams = await getStaticParams("/docs/");
return staticParams;
};
```
Expand All @@ -171,7 +171,7 @@ It is recommended to place the Robindoc initialization near this route.
```ts filename="app/docs/robindoc.ts" switcher tab="TypeScript" clone="js|JavaScript|app/docs/robindoc.js"
import { initializeRobindoc } from "robindoc";

export const { Page, Sidebar, getPages, getMeta, getPageContent } =
export const { Page, Sidebar, getStaticParams, getMetadata, getPageData } =
initializeRobindoc({
configuration: {
sourceRoot: "../docs",
Expand Down Expand Up @@ -339,21 +339,21 @@ const nextConfig: NextConfig = {
};
```
For more details on search configuration, refer to the [Search](../03-customization/03-search.md) page.
For more details on search configuration, refer to the [Search](../03-customization/04-search.md) page.
## Sitemap Setup
To generate a sitemap in next.js, you can use a [special sitemap file](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap) in combination with [getPages](../03-customization/02-tools/get-pages.md) tool:
To generate a sitemap in next.js, you can use a [special sitemap file](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap) in combination with [getStaticParams](../03-customization/02-tools/get-static-params.md) tool:
```ts filename="app/sitemap.ts" switcher tab="TypeScript"
import { type MetadataRoute } from "next";
import { getPages } from "./docs/robindoc";
import { getStaticParams } from "./docs/robindoc";

const sitemap = async (): Promise<MetadataRoute.Sitemap> => {
const pages = await getPages();
const staticParams = await getStaticParams();

return pages.map((page) => ({
url: `https://robindoc.com${page}`,
return staticParams.map(({ segments }) => ({
url: `https://robindoc.com${segments.join("/")}`,
lastModified: new Date(),
changeFrequency: "daily",
priority: 0.7,
Expand All @@ -365,13 +365,13 @@ export default sitemap;
```js filename="app/sitemap.js" switcher tab="JavaScript"
import { type MetadataRoute } from "next";
import { getPages } from "./docs/robindoc";
import { getStaticParams } from "./docs/robindoc";

const sitemap = async () => {
const pages = await getPages();
const staticParams = await getStaticParams();

return pages.map((page) => ({
url: `https://robindoc.com${page}`,
return staticParams.map(({ segments }) => ({
url: `https://robindoc.com/${segments.join('/')}`,
lastModified: new Date(),
changeFrequency: "daily",
priority: 0.7,
Expand Down
2 changes: 1 addition & 1 deletion docs/02-structure/02-items.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ export const { Page, Sidebar } = initializeRobindoc({

In automatic mode, Robindoc first looks for a `structure.json` file in the current directory.

If the `structure.json` file is not in the current directory, Robindoc will try to create the structure on its own based on the files in the directory. In this case, it will determine all paths, slugs, as well as the header for the sidebar link. The header is formed according to the same principles as the meta-header. Learn more about getting metadata on the [Get Meta](../03-customization/02-tools/get-meta.md) page.
If the `structure.json` file is not in the current directory, Robindoc will try to create the structure on its own based on the files in the directory. In this case, it will determine all paths, slugs, as well as the header for the sidebar link. The header is formed according to the same principles as the meta-header. Learn more about getting metadata on the [Get Meta](../03-customization/02-tools/get-metadata.md) page.

## structure.json

Expand Down
2 changes: 1 addition & 1 deletion docs/03-customization/01-elements/header.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ All customization in Robindoc happens through the structure and props of the com

`links` [`{ title: string; href: string }[]`] - a list of links to pages on your site unrelated to the documentation section. This could include blog, showcases, about, etc.;

`searcher` - the route for search functionality or a client-side async callback. If this field is not provided, search functionality will not be available. Read more on the "[Search](../03-search.md)" page;
`searcher` - the route for search functionality or a client-side async callback. If this field is not provided, search functionality will not be available. Read more on the "[Search](../04-search.md)" page;

`translations` [`{ [key: string]: string }`] - translations for the current block. The key is the term identifier, and the value is the corresponding translation. _For the latest list of terms, check the editor hints_;

Expand Down
4 changes: 2 additions & 2 deletions docs/03-customization/02-tools/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ These utilities work based on the structure and documentation files. They are ne
```ts filename="app/docs/robindoc.ts" switcher tab="TypeScript" clone="js|JavaScript|app/docs/robindoc.js"
import { initializeRobindoc } from "robindoc";

export const { Page, Sidebar, getPages, getMeta, getPageContent } =
export const { Page, Sidebar, getStaticParams, getMetadata, getPageData } =
initializeRobindoc({
configuration: {
sourceRoot: "../docs",
Expand All @@ -18,4 +18,4 @@ export const { Page, Sidebar, getPages, getMeta, getPageContent } =
});
```

For more information on using the utilities, refer to their respective pages - [`getMeta`](./get-meta.md), [`getPages`](./get-pages.md), [`getPageContent`](./get-page-content.md).
For more information on using the utilities, refer to their respective pages - [`getMetadata`](./get-metadata.md), [`getStaticParams`](./get-static-params.md), [`getPageData`](./get-page-data.md).
55 changes: 0 additions & 55 deletions docs/03-customization/02-tools/get-meta.md
View file

This file was deleted.

Loading

0 comments on commit 406d474

Please sign in to comment.