Gibook migration guide

Author: kiptoo

README_Migrate_Gitbook.mdx

@@ -0,0 +1,211 @@
+---
+sidebar_position: 2.5
+sidebar_label: Gitbook Migration
+slug: /gitbook-migration
+description: How to migrate from GitBook to Docusaurus
+---
+
+# Migrate GitBook to Docusaurus
+
+This page explains how to migrate from GitBook to Docusaurus. For newcomers, Docusaurus is a static-site generator. It builds a single-page application with fast client-side navigation, leveraging the full power of React to make your site interactive. It provides out-of-the-box documentation features but can be used to create any kind of site (personal website, product, blog, marketing landing pages, etc).
+
+## Key Features
+
+Docusaurus is built with high attention to the developer and contributor experience.
+
+⚛️ Built with 💚 and React:
+
+Extend and customize with React
+Gain full control of your site's browsing experience by providing your own React components
+
+Pluggable:
+
+Bootstrap your site with a basic template, then use advanced features and plugins
+Open source your plugins to share with the community
+
+✂️ Developer experience:
+
+Start writing your docs right now
+Universal configuration entry point to make it more maintainable by contributors
+Hot reloading with lightning-fast incremental build on changes
+Route-based code and data splitting
+Publish to GitHub Pages, Netlify, Vercel, and other deployment services with ease
+Our shared goal—to help your users quickly find what they need and understand your products better. We share our best practices to help you build your docs site right and well.
+
+🎯 SEO friendly:
+
+HTML files are statically generated for every possible path.
+Page-specific SEO to help your users land on your official docs directly relating their problems at hand.
+
+📝 Powered by MDX:
+
+Write interactive components via JSX and React embedded in Markdown.
+Share your code in live editors to get your users to love your products on the spot.
+
+🔍 Search:
+Your full site is searchable.
+
+💾 Document Versioning:
+
+Helps you keep documentation in sync with project releases.
+
+🌍 Internationalization (i18n):
+Translate your site in multiple locales.
+
+Docusaurus 2 is born to be compassionately accessible to all your users, and lightning-fast.
+
+⚡️ Lightning-fast.
+
+Docusaurus 2 follows the PRPL Pattern that makes sure your content loads blazing fast.
+
+🦖 Accessible.
+Attention to accessibility, making your site equally accessible to all users.
+
+# Migration Steps
+
+## step 1 - Generate a new Docusaurus site
+
+Generate a new Docusaurus site using the classic template.
+
+The classic template will automatically be added to your project after you run the command:
+
+```bash
+npm init docusaurus@latest my-website classic
+```
+
+You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
+
+The command also installs all necessary dependencies you need to run Docusaurus.
+
+## step 2 - Start your site
+
+Run the development server:
+
+```bash
+cd my-website
+npm run start
+```
+
+The cd command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
+
+The npm run start command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
+
+Open docs/intro.md (this page) and edit some lines: the site reloads automatically and displays your changes.
+
+## step 3 - copy documentation content from GitBook to docusaurus
+
+1. First Navigate to docs folder and delee the generated tutorial docs from docusaurus ,
+2. Navigate to gibook project folder copy all contents except .git and .gibook and move them to the docusaurus project under docs/
+3. Convert all doc files from md to mdx extension
+4. you will get this error "DocNavbarItem: couldn't find any doc with id "intro" in version current". Available doc ids are: ..""
+   this is because the navbar is set to the previous deleted tutorial doc files in step 1.
+
+   ### Solution
+
+   go to docusaurus.config.js at the root of the project Edit themeConfig:navbar:items[0] change docId docId: "app-generator",
+   to one of the available doc ids from the error above
+
+5. Build the project run:
+
+```bash
+npm run build
+```
+
+# SSR
+
+1. Create a ssr folder on the root of docusaurus project
+
+2. Create file index.js inside ssr folder and add below code
+
+```jsx title="/ssr/index.js"
+const express = require("express");
+const fs = require("fs");
+const path = require("path");
+
+// create express application
+const app = express();
+
+const distFolder = path.join(process.cwd(), "../build");
+
+app.set("view engine", "html");
+app.set("views", distFolder);
+
+// app.get(
+// 	"/appSeed//.(js|css|map|ico|svg|png|jpg|jpeg)$/",
+// 	express.static(distFolder, {
+// 		maxAge: "1y",
+// 	})
+// );
+// serve static assets
+app.get(/\.(js|css|map|ico|svg|png|jpg|jpeg|woff2)$/, express.static(path.resolve(__dirname, "../build")));
+
+// for any other requests, send `index.html` as a response
+
+app.get("/sitemap.xml", (req, res) => {
+	let indexHTML = fs.readFileSync(path.resolve(__dirname, "../build/" + req.originalUrl), {
+		encoding: "utf8",
+	});
+
+	// set header and status
+	res.contentType("text/xml");
+	res.status(200);
+
+	return res.send(indexHTML);
+});
+app.get("/opensearch.xml", (req, res) => {
+	let indexHTML = fs.readFileSync(path.resolve(__dirname, "../build/" + req.originalUrl), {
+		encoding: "utf8",
+	});
+
+	// set header and status
+	res.contentType("text/xml");
+	res.status(200);
+
+	return res.send(indexHTML);
+});
+app.get("/favicon.ico", (req, res) => {
+	let indexHTML = fs.readFileSync(path.resolve(__dirname, "../build/" + req.originalUrl), {
+		encoding: "utf8",
+	});
+
+	// set header and status
+	res.contentType("png");
+	res.status(200);
+
+	return res.send(indexHTML);
+});
+
+app.use("*", (req, res) => {
+	if (req.originalUrl.includes("assets")) return express.static(path.resolve(__dirname, "../build/" + req.originalUrl));
+	console.log("url", req.originalUrl);
+	// console.log("method", req.method);
+	let indexHTML;
+	// read `index.html` file
+	if (req.originalUrl == "/") {
+		indexHTML = fs.readFileSync(path.resolve(__dirname, "../build/index.html"), {
+			encoding: "utf8",
+		});
+	} else {
+		indexHTML = fs.readFileSync(path.resolve(__dirname, "../build/" + req.originalUrl + "/index.html"), {
+			encoding: "utf8",
+		});
+	}
+
+	// set header and status
+	res.contentType("text/html");
+	res.status(200);
+
+	return res.send(indexHTML);
+});
+
+// run express server on port 9000
+app.listen("9000", () => {
+	console.log("Express server started at http://localhost:9000");
+});
+```
+
+3. run the ssr version of the app after building project
+
+```bash
+node ssr/index.js
+```