Merge pull request #316 from vordgi/rd-314

rd-314 use next out of the box

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 (
     <RobinProvider>
@@ -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)";

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).
 

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
 

docs/01-getting-started/04-app-organization/next-js.md → 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 (
-    <>
-      <Sidebar pathname={pathname} />
-      <Page pathname={pathname} />
-    </>
-  );
+  return <Page pathname={pathname} />;
 };
 ```
 
-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 (
     <RobinProvider>
-      <Header logo={<Logo />} link={Link} />
-      <Main>{children}</Main>
+      <Header logo={<Logo />} />
+      <Main>
+        <Sidebar />
+        {children}
+      </Main>
       <Footer copyright="© 2024 All rights reserved" />
     </RobinProvider>
   );
 };
 ```
 
-For more details on configuring elements, refer to the [`RobinProvider`](../../03-customization/01-elements/robin-provider.md), [`Header`](../../03-customization/01-elements/header.md), [`Footer`](../../03-customization/01-elements/footer.md), and [`Main`](../../03-customization/01-elements/main.md) block pages.
+For more details on configuring elements, refer to the [`RobinProvider`](../../03-customization/01-elements/robin-provider.md), [`Header`](../../03-customization/01-elements/header.md), [`Sidebar`](../../03-customization/01-elements/sidebar.md), [`Footer`](../../03-customization/01-elements/footer.md), and [`Main`](../../03-customization/01-elements/main.md) block pages.
 
 ## Search Setup
 
@@ -117,28 +136,22 @@ export const GET = async (request: Request) => {
 ```
 
 ```tsx switcher filename="app/docs/layout.tsx" tab="TypeScript"
-import { Layout } from "robindoc";
-
 export const Layout = ({ children }) => {
   return (
     <RobinProvider>
       <Header logo={<Logo />} searcher="/api/search" />
-      <Main>{children}</Main>
-      <Footer copyright="© 2024 All rights reserved" />
+      {/* ... */}
     </RobinProvider>
   );
 };
 ```
 
 ```js switcher filename="app/docs/layout.js" tab="JavaScript"
-import { Layout } from "robindoc";
-
 export const Layout = ({ children }) => {
   return (
     <RobinProvider>
       <Header logo={<Logo />} searcher="/api/search" />
-      <Main>{children}</Main>
-      <Footer copyright="© 2024 All rights reserved" />
+      {/* ... */}
     </RobinProvider>
   );
 };
@@ -167,7 +180,7 @@ To generate a sitemap in next.js, you can use a [special sitemap file](https://n
 
 ```ts filename="./app/sitemap.ts"
 import { type MetadataRoute } from "next";
-import { getPages } from "./docs/[[...path]]/robindoc";
+import { getPages } from "./docs/robindoc";
 
 export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
   const pages = await getPages();

docs/01-getting-started/README.md

@@ -6,13 +6,12 @@ To start using Robindoc, follow these steps:
 
 2. [Initialize Robindoc](./03-initialization.md);
 
-3. [Configure documentation pages for your framework](./04-app-organization/README.md)
-   - [Organizing an application with Next.js](./04-app-organization/next-js.md)
+3. [Configure documentation pages](./04-app-organization.md)
 
 ## Requirements
 
 Node.js version 18.0.0 or later. It is recommended to use Node.js v20.0.0 or higher.
 
 React.js version 19.0.0 (including experimental and canary channels) or later.
 
-A framework that supports React Server Components in its configuration.
+Next.js App Router.

docs/02-structure/02-items.md

@@ -12,7 +12,7 @@ Each item consists of the following keys:
 
 Firstly, Robindoc reads the structure passed as an argument:
 
-```ts filename="robindoc.ts"
+```ts filename="/docs/robindoc.ts"
 export const { Page, Sidebar } = initializeRobindoc({
   // ...
   items: [
@@ -49,7 +49,7 @@ export const { Page, Sidebar } = initializeRobindoc({
 
 You can also pass an asynchronous callback as an argument. In this case, you can form the structure in a way that suits you.
 
-```ts filename="robindoc.ts"
+```ts filename="/docs/robindoc.ts"
 export const { Page, Sidebar } = initializeRobindoc(async () => {
   const items = await loadItems();
 
@@ -70,7 +70,7 @@ This configuration determines the list of available and generated pages, all lin
 
 To have the subtree generated automatically, you need to pass `items: 'auto'`.
 
-```ts filename="robindoc.ts"
+```ts filename="/docs/robindoc.ts"
 export const { Page, Sidebar } = initializeRobindoc({
   // ...
   items: "auto",
@@ -79,7 +79,7 @@ export const { Page, Sidebar } = initializeRobindoc({
 
 You can add extra elements from third-party sources to automatically generated elements - `items: [YOUR_OPTIONS, 'auto']`
 
-```ts filename="robindoc.ts"
+```ts filename="/docs/robindoc.ts"
 import { initializeRobindoc } from "robindoc";
 
 export const { Page, Sidebar } = initializeRobindoc({
@@ -103,7 +103,7 @@ export const { Page, Sidebar } = initializeRobindoc({
 
 This, like any configuration setting, can be done anywhere in the structure.
 
-```ts filename="robindoc.ts"
+```ts filename="/docs/robindoc.ts"
 export const { Page, Sidebar } = initializeRobindoc({
   // ...
   items: [

docs/02-structure/03-data-source.md

@@ -6,7 +6,7 @@ Currently, full support for the file system and GitHub is built-in. If you want
 
 By default, documentation is built from the current directory. To reconfigure Robindoc to another source, simply change the `sourceRoot` in the required branch of the structure ([learn more about structure configuration](./01-configuration.md)).
 
-```ts
+```ts filename="/docs/robindoc.ts"
 export const { Page, Sidebar } = initializeRobindoc(async () => ({
   configuration: {
     sourceRoot: "../docs",
@@ -27,7 +27,7 @@ In the case of a remote Git repository, you can specify URLs for individual bran
 
 You can generate a token at https://github.com/settings/tokens?type=beta. For private repositories it should have read-only access to `contents`.
 
-```ts
+```ts filename="/docs/robindoc.ts"
 import { initializeRobindoc } from "robindoc";
 
 export const { Page, Sidebar } = initializeRobindoc({
@@ -42,7 +42,7 @@ export const { Page, Sidebar } = initializeRobindoc({
 
 Robindoc can assemble the structure from different sources, for example, one section from a local system and another from a remote Git repository.
 
-```ts
+```ts filename="/docs/robindoc.ts"
 import { initializeRobindoc } from "robindoc";
 
 export const { Page, Sidebar } = initializeRobindoc({

docs/02-structure/README.md

@@ -2,7 +2,7 @@
 
 The structure is the core component of Robindoc. Here you can describe all possible documentation pages and configure the main information for them. Robindoc fully supports both automatic structure generation and custom methods for assembling it. For more details, read the [Items](./02-items.md) page.
 
-```ts
+```ts filename="/docs/robindoc.ts"
 import { initializeRobindoc } from "robindoc";
 
 export const { Page, Sidebar } = initializeRobindoc({

docs/03-customization/01-elements/README.md

@@ -14,14 +14,14 @@ The documentation layout consists of several elements: `Layout`, `Main`, `Keylin
 
 - [`KeylinkToContent` and `KeylinkToNavigation`](./keylinks.md) are special components designed to improve accessibility.
 
-- [`Sidebar`](./sidebar.md) is responsible for side navigation. It displays all available documentation pages with nesting levels. This component is rendered on each page and depends on the generated structure.
+- [`Sidebar`](./sidebar.md) is responsible for side navigation. It displays all available documentation pages with nesting levels. This component is rendered on each page and depends on the generated structure. Sidebar is independent component and you can use it once across the entire section.
 
 - [`Page`](./page.md) is responsible for the content of the document itself. It handles displaying markdown-based files as HTML. This component is rendered on each page and depends on the generated structure.
 
 ## Blocks usage
 
-`Header`, `Footer`, `RobinProvider`, `Main`, `KeylinkToContent`, and `KeylinkToNavigation` are global elements. It is recommended to include them on all documentation pages.
+`Header`, `Footer`, `RobinProvider`, `Main`, `KeylinkToContent`, `KeylinkToNavigation` and `Sidebar` are global elements. It is recommended to include them under all documentation pages.
 
-`Page` and `Sidebar` are dynamic elements and should be added to each page.
+`Page` is dynamic elements and should be added to each page.
 
-The specific usage of the elements depends on the chosen framework. For more details on using these elements, refer to the section [App organization](../../01-getting-started/04-app-organization/README.md).
+For more details on using these elements, refer to the section [App organization](../../01-getting-started/04-app-organization.md).

docs/03-customization/01-elements/footer.md

@@ -29,4 +29,4 @@ All customization in Robindoc happens through the structure and props of the com
 
 `Footer` is an independent component and doesn't rely on any specific page. It's assumed you can use it once across the entire project or section.
 
-The specific usage of the component depends on the chosen framework. For more details on using `Footer`, refer to the section [App organization](../../01-getting-started/04-app-organization/README.md).
+For more details on using `Footer`, refer to the section [App organization](../../01-getting-started/04-app-organization.md).