diff --git a/README.md b/README.md index 375b9217..f1e46a28 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ Read the documentation in a convenient interface at [robindoc.com/docs](https:// Robindoc is a framework for automatically creating documentation websites based on markdown files, built on React.js Server Components. -```tsx +```tsx filename="/docs/page.tsx" export const Documentation = () => { return ( @@ -34,8 +34,8 @@ No additional configuration is needed, while preserving the accessibility and cl ## Advantages -- Works on React.js Server Components (RSC). The framework choice is up to you. More details in the section "[App Organization](./docs/01-getting-started/04-app-organization/README.md)"; -- Requires no configuration of the project, bundler, or markdown documents. More details in the section "[Customization](./docs/03-customization/README.md)"; +- Works on React.js Server Components (RSC). More details in the section "[App Organization](./docs/01-getting-started/04-app-organization.md)"; +- Zero configuration of the project, bundler, or markdown documents. More details in the section "[Customization](./docs/03-customization/README.md)"; - Supports loading content from various sources, including GitHub. More details in the section "[Data Source](./docs/02-structure/03-data-source.md)"; - Supports fully automatic documentation generation, as well as custom generation. More details in the section "[Structure](./docs/02-structure/README.md)"; - Supports JSX/HTML and special Robin components for all sources. More details in the section "[Writing MD](./docs/01-getting-started/02-writing-md.md)"; diff --git a/docs/01-getting-started/01-installation.md b/docs/01-getting-started/01-installation.md index 3e4c14c9..c3b54896 100644 --- a/docs/01-getting-started/01-installation.md +++ b/docs/01-getting-started/01-installation.md @@ -1,8 +1,6 @@ # Installation -Robindoc is simply a helper framework, meaning it does not include React itself or its frameworks. Additionally, Robindoc does not depend on any specific solutions. - -If you do not yet have an application, initialize it according to the instructions of the framework you are comfortable with (that supports RSC). +Robindoc is simply a helper framework, meaning it does not include React itself or its frameworks. _If you do not yet have an application, initialize it according to the instructions._ If you already have an application on a framework that supports RSC, simply install the `robindoc` package. After that, you can fully integrate it into your application by [initializing Robindoc](./03-initialization.md). diff --git a/docs/01-getting-started/03-initialization.md b/docs/01-getting-started/03-initialization.md index 51c05f2e..c6bbfe87 100644 --- a/docs/01-getting-started/03-initialization.md +++ b/docs/01-getting-started/03-initialization.md @@ -6,7 +6,7 @@ To use Robindoc with all its features, you need to initialize it. To do this, yo 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). -```ts +```ts filename="/docs/robindoc.ts" import { initializeRobindoc } from "robindoc"; export const { Page, Sidebar, getPages, getMeta, getPageContent } = @@ -20,7 +20,7 @@ export const { Page, Sidebar, getPages, getMeta, getPageContent } = }); ``` -Now, use these elements in the necessary places. For more details, read the "[App Organization](./04-app-organization/README.md)" section. +Now, use these elements in the necessary places. For more details, read the "[App Organization](./04-app-organization.md)" section. ## File Location diff --git a/docs/01-getting-started/04-app-organization/next-js.md b/docs/01-getting-started/04-app-organization.md similarity index 63% rename from docs/01-getting-started/04-app-organization/next-js.md rename to docs/01-getting-started/04-app-organization.md index aa18a740..d050b9fc 100644 --- a/docs/01-getting-started/04-app-organization/next-js.md +++ b/docs/01-getting-started/04-app-organization.md @@ -1,34 +1,49 @@ -# Application Organization for Next.js +# App Organization -Currently, Robindoc works only with the App Router. Once RSC is available for the Pages Router, Robindoc will automatically support it as well. +Robindoc can be considered to consist of several parts: + +- Documentation Structure ([more about documentation structure](../../02-structure/README.md)); +- Robindoc Initialization ([more about initialization](../03-initialization.md)); +- Page Markup and Configuration ([more about customization](../../03-customization/README.md)); +- Documentation Markdown Files ([more about writing MD](../02-writing-md.md)). + +## Organizing Documentation Files + +One of the main advantages of Robindoc is that documentation files can reside in any source — whether they are files outside the current directory or a remote git repository (more about sources on the "[Data Source](../../02-structure/03-data-source.md)" page). + +Robindoc’s main approach is that you don’t adjust the location of markdown files for Robindoc; instead, Robindoc builds the site from your markdown files. In other words, you place files so that they can be read in GitHub, and Robindoc serves as a convenient interface. + +However, when using the automatic mode for generating the structure, the documentation file structure should match the desired structure on the site. In manual mode, you can organize the documentation files as you wish, but it is still recommended to reflect the site’s structure. + +## Application Setup and Configuration 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. + +Global elements - [`RobinProvider`](../../03-customization/01-elements/robin-provider.md), [`Header`](../../03-customization/01-elements/header.md), [`Footer`](../../03-customization/01-elements/footer.md), [`Main`](../../03-customization/01-elements/main.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. + ## Page Setup 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" -import { Page, Sidebar, getMeta, getPages } from "./robindoc"; +import { Page, Sidebar, getMeta, getPages } from "../robindoc"; export const Page: React.FC<{ params: { path?: string[] } }> = ({ params }) => { const pathname = "/docs/" + (params.path?.join("/") || ""); - return ( - <> - - - - ); + return ; }; ``` -For more details about the props, refer to the [`Sidebar`](../../03-customization/01-elements/sidebar.md) and [`Page`](../../03-customization/01-elements/page.md) block pages. +For more details about the props, refer to the [`Page`](../../03-customization/01-elements/page.md) element page. You should also set up metadata generation and static parameters generation (if you want to use SSG, which is highly recommended): -```tsx -import { Page, Sidebar, getMeta, getPages } from "./robindoc"; +```tsx filename="app/docs/[[...path]]/page.tsx" +import { Page, Sidebar, getMeta, getPages } from "../robindoc"; // ... @@ -53,7 +68,7 @@ export const generateStaticParams = async () => { It is recommended to place the Robindoc initialization near this route. -```tsx filename="app/docs/[[...path]]/robindoc.ts" +```tsx filename="app/docs/robindoc.ts" import { initializeRobindoc } from "robindoc"; export const { Page, Sidebar, getPages, getMeta, getPageContent } = @@ -79,22 +94,26 @@ The Next.js Layout should be placed one level up so that it remains static for a ```tsx filename="app/docs/layout.tsx" import { RobinProvider, Header, Footer, Main } from "robindoc"; -import Link from "next/link"; +import { Sidebar } from "./robindoc"; import Logo from "./logo"; + import "robindoc/lib/styles.css"; export const Layout = ({ children }) => { return ( -
} link={Link} /> -
{children}
+
} /> +
+ + {children} +