From 0b0dabd65fe075dfedbc27bc5eb3c4b596bddea3 Mon Sep 17 00:00:00 2001 From: phshy0607 Date: Wed, 30 Mar 2022 17:25:14 +0800 Subject: [PATCH 01/10] feat: add defineConfig --- docs/.docit/docit.config.js | 6 ++++-- src/node/index.ts | 8 ++++++-- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/.docit/docit.config.js b/docs/.docit/docit.config.js index 6e31e06..09dafd2 100644 --- a/docs/.docit/docit.config.js +++ b/docs/.docit/docit.config.js @@ -1,4 +1,6 @@ -const config = { +import { defineConfig } from "../../src/node/index"; + +const config = defineConfig({ title: "Docit", publicPath: "https://phshy0607.github.io/docit/", sidebars: [ @@ -23,5 +25,5 @@ const config = { }, { title: "Troubleshooting", path: "/troubleshooting" }, ], -}; +}); export default config; diff --git a/src/node/index.ts b/src/node/index.ts index 331173a..83b9398 100644 --- a/src/node/index.ts +++ b/src/node/index.ts @@ -1,2 +1,6 @@ -export * from './start.js'; -export * from './build.js'; +import { UserFileConfig } from "./types.js"; + +export * from "./start.js"; +export * from "./build.js"; + +export const defineConfig = (config: UserFileConfig) => config; From 2f12510dd79cf848e7450983e024b8ce3686d78a Mon Sep 17 00:00:00 2001 From: phshy0607 Date: Wed, 30 Mar 2022 17:25:41 +0800 Subject: [PATCH 02/10] fix: avoid using dirname__ --- src/node/constants.ts | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/node/constants.ts b/src/node/constants.ts index be3cb1f..c651f35 100644 --- a/src/node/constants.ts +++ b/src/node/constants.ts @@ -1,13 +1,13 @@ -import path from 'path'; -import { fileURLToPath } from 'url'; +import path from "path"; +import { fileURLToPath } from "url"; -const __dirname = fileURLToPath(import.meta.url); -export const PKG_JSON_PATH = path.resolve(__dirname, '../../../package.json'); -export const CLIENT_PATH = path.resolve(__dirname, '../../client'); +const dirname__ = fileURLToPath(import.meta.url); +export const PKG_JSON_PATH = path.resolve(dirname__, "../../../package.json"); +export const CLIENT_PATH = path.resolve(dirname__, "../../client"); -export const MD_PATTERN = '**/*.md?(x)'; +export const MD_PATTERN = "**/*.md?(x)"; -export const VIRTUAL_ROUTER_CONFIG_ID = 'virtual:routes'; -export const VIRTUAL_APP_DATA_ID = 'virtual:appData'; -export const VIRTUAL_SIDEBARS_CONFIG_ID = 'virtual:sidebars'; -export const VIRTUAL_PROVIDER_PATH_ID = 'virtual:provider'; +export const VIRTUAL_ROUTER_CONFIG_ID = "virtual:routes"; +export const VIRTUAL_APP_DATA_ID = "virtual:appData"; +export const VIRTUAL_SIDEBARS_CONFIG_ID = "virtual:sidebars"; +export const VIRTUAL_PROVIDER_PATH_ID = "virtual:provider"; From 7d47b6abe9e19b67cd03b02f88c20d60e1f1e8da Mon Sep 17 00:00:00 2001 From: phshy0607 Date: Wed, 30 Mar 2022 17:25:56 +0800 Subject: [PATCH 03/10] chore: update CHANGELOG.md --- CHANGELOG.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 11c7c5a..8a9e1eb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,10 +12,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `Fixed` for any bug fixes. - `Security` in case of vulnerabilities. +## [UNRELEASED] + +### Added +- add `defineConfig`, to help write config file. +- add `ESM` info in `ReadMe` and `docs` + ## [0.6.4] - 2022-03-29 -### added +### Added - use `yarn release` to publish packages ## [0.6.2] - 2022-03-29 From aac5a47bc48c97e10b2c17a2095b0356185e8be1 Mon Sep 17 00:00:00 2001 From: phshy0607 Date: Wed, 30 Mar 2022 17:28:10 +0800 Subject: [PATCH 04/10] chore: add `esm` info --- README.md | 2 ++ docs/index.mdx | 2 ++ 2 files changed, 4 insertions(+) diff --git a/README.md b/README.md index f3dd00c..2bd1b1d 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,8 @@ ## Get Started +This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required. + ```sh yarn add @blizzbolts/docit -D ``` diff --git a/docs/index.mdx b/docs/index.mdx index 98bfb88..232d8ee 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -13,6 +13,8 @@ title: Introduction ## Install +This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required. + ```sh yarn add @blizzbolts/docit -D ``` From a1afb88a2ed17ce002f9936f07d926e7f28e496c Mon Sep 17 00:00:00 2001 From: phshy0607 Date: Wed, 30 Mar 2022 17:57:22 +0800 Subject: [PATCH 05/10] feat: encapsulate svgs --- src/client/components/Header/index.tsx | 29 ++++----- src/client/components/Loading/index.tsx | 45 +------------ src/client/components/Svgs/index.tsx | 87 +++++++++++++++++++++++++ 3 files changed, 101 insertions(+), 60 deletions(-) create mode 100644 src/client/components/Svgs/index.tsx diff --git a/src/client/components/Header/index.tsx b/src/client/components/Header/index.tsx index ce68825..41428b1 100644 --- a/src/client/components/Header/index.tsx +++ b/src/client/components/Header/index.tsx @@ -1,31 +1,26 @@ -import React from 'react'; -import { StyledHeader } from '../../styled'; -import appData from 'virtual:appData'; -import { StyledSidebarBtn, StyledTitle } from './styled'; -import { setSidebarVisible, sidebarVisible } from '../../model'; +import React from "react"; + +import { StyledSidebarBtn, StyledTitle, StyledHeader } from "./styled"; +import { setSidebarVisible, sidebarVisible } from "../../model"; +import { Socials } from "../Socials"; +import { Svgs } from "../Svgs"; + +import appData from "virtual:appData"; const Header = () => { const visible = sidebarVisible.use(); return ( - + { setSidebarVisible(!visible); }} > - - - + {appData.title} + + ); }; diff --git a/src/client/components/Loading/index.tsx b/src/client/components/Loading/index.tsx index 35f98ad..0516175 100644 --- a/src/client/components/Loading/index.tsx +++ b/src/client/components/Loading/index.tsx @@ -1,6 +1,7 @@ import React from "react"; import { LoadingProps } from "./types"; import { StyledLoadingContainer } from "./styled"; +import { Svgs } from "../Svgs"; const Loading: React.FC = (props) => { const { loading, children } = props; @@ -11,49 +12,7 @@ const Loading: React.FC = (props) => { return ( - - - - - - - - - - - + ); }; diff --git a/src/client/components/Svgs/index.tsx b/src/client/components/Svgs/index.tsx new file mode 100644 index 0000000..8e44471 --- /dev/null +++ b/src/client/components/Svgs/index.tsx @@ -0,0 +1,87 @@ +import React, { SVGAttributes } from "react"; + +interface SvgProps extends SVGAttributes { + className?: string; + style?: React.CSSProperties; +} + +const Github: React.FC = (props) => { + return ( + + GitHub + + + ); +}; + +const ToggleBtn: React.FC = (props) => { + return ( + + + + ); +}; + +const AnimatedLoading: React.FC = (props) => { + return ( + + + + + + + + + + + + ); +}; + +export const Svgs = { + Github, + ToggleBtn, + AnimatedLoading, +}; From 3e272fc0fce5bc76288109aa267aa7004524b581 Mon Sep 17 00:00:00 2001 From: phshy0607 Date: Wed, 30 Mar 2022 17:57:50 +0800 Subject: [PATCH 06/10] feat: rearrange styled components --- src/client/components/Document/index.tsx | 50 +++++++++++---------- src/client/components/Document/styled.ts | 19 ++++++++ src/client/components/Header/styled.ts | 13 +++++- src/client/components/Sidebar/index.tsx | 13 ++++-- src/client/components/Sidebar/styled.ts | 20 ++++++++- src/client/index.tsx | 20 ++++----- src/client/styled/index.ts | 57 ------------------------ 7 files changed, 94 insertions(+), 98 deletions(-) diff --git a/src/client/components/Document/index.tsx b/src/client/components/Document/index.tsx index fc5bf72..d7e9d75 100644 --- a/src/client/components/Document/index.tsx +++ b/src/client/components/Document/index.tsx @@ -3,7 +3,7 @@ import { routes } from "virtual:routes"; import { renderRoutes } from "react-router-config"; import { MDXProvider } from "@mdx-js/react"; import { ShowCode } from "../../built-in/ShowCode"; -import { StyledMarkdown } from "./styled"; +import { StyledMarkdown, StyledDocument } from "./styled"; import { ApiTable } from "../../built-in/ApiTable"; import { useDefaultRoute } from "../../hooks/useDefaultRoute"; import { ErrorBoundary } from "../ErrorBoundary"; @@ -11,29 +11,31 @@ import { ErrorBoundary } from "../ErrorBoundary"; const Document = () => { useDefaultRoute(); return ( - - - { - return ( - - {props.children} - - ); - }, - }} - > - }>{renderRoutes(routes)} - - - + + + + { + return ( + + {props.children} + + ); + }, + }} + > + }>{renderRoutes(routes)} + + + + ); }; -export default Document; +export { Document }; diff --git a/src/client/components/Document/styled.ts b/src/client/components/Document/styled.ts index 8c1581f..57ad695 100644 --- a/src/client/components/Document/styled.ts +++ b/src/client/components/Document/styled.ts @@ -1,7 +1,26 @@ import styled from "styled-components"; +export const StyledDocument = styled.main` + width: calc(100vw - var(--sidebar-width)); + height: calc(100vh - var(--header-height)); + display: inline-block; + overflow-y: auto; + + @media (max-width: 768px) { + width: 100vw; + padding-left: 0rem; + } +`; + export const StyledMarkdown = styled.div` color: var(--c-1); + padding: 0 4em; + word-break: break-all; + margin-bottom: 100px; + + @media (max-width: 768px) { + padding: 0 1em; + } h1, h2, diff --git a/src/client/components/Header/styled.ts b/src/client/components/Header/styled.ts index b257f84..de1ee7e 100644 --- a/src/client/components/Header/styled.ts +++ b/src/client/components/Header/styled.ts @@ -1,4 +1,15 @@ -import styled from 'styled-components'; +import styled from "styled-components"; + +export const StyledHeader = styled.header` + height: var(--header-height); + width: 100%; + background: var(--c-bg); + border-bottom: 1px solid var(--c-divider); + + display: flex; + align-items: center; + padding: 0 2rem; +`; export const StyledTitle = styled.p` font-weight: bold; diff --git a/src/client/components/Sidebar/index.tsx b/src/client/components/Sidebar/index.tsx index 1c900f9..e709115 100644 --- a/src/client/components/Sidebar/index.tsx +++ b/src/client/components/Sidebar/index.tsx @@ -2,10 +2,11 @@ import React from "react"; import { Link, useLocation } from "react-router-dom"; import { isEmpty } from "lodash-es"; import sidebars from "virtual:sidebars"; -import { StyledSidebarItem } from "./styled"; -import { setSidebarVisible } from "../../model"; +import { StyledSidebarItem, StyledAside } from "./styled"; +import { setSidebarVisible, sidebarVisible } from "../../model"; -const Sidebar: React.FC = (props) => { +const Sidebar: React.FC = () => { + const visible = sidebarVisible.use(); const location = useLocation(); const parse = (o: SidebarNode, level?: number) => { if (isEmpty(o.children)) { @@ -39,7 +40,11 @@ const Sidebar: React.FC = (props) => { } }; - return ; + return ( + + {sidebars.map((o) => parse(o, 0))} + + ); }; export { Sidebar }; diff --git a/src/client/components/Sidebar/styled.ts b/src/client/components/Sidebar/styled.ts index bea523d..eed875e 100644 --- a/src/client/components/Sidebar/styled.ts +++ b/src/client/components/Sidebar/styled.ts @@ -1,6 +1,24 @@ import styled from "styled-components"; import { StyledSidebarItemProps } from "./types"; +export const StyledAside = styled.aside<{ visible: string }>` + padding: 2rem 2rem; + width: var(--sidebar-width); + height: calc(100vh - var(--header-height)); + overflow-y: auto; + display: inline-block; + border-right: 1px solid var(--c-divider); + background: white; + + @media (max-width: 768px) { + position: fixed; + left: ${(props) => + props.visible === "true" ? 0 : "calc(-1 * var(--sidebar-width))"}; + + transition: left 250ms ease-in-out; + } +`; + export const StyledSidebarItem = styled.div.attrs( (props) => { return { @@ -10,7 +28,7 @@ export const StyledSidebarItem = styled.div.attrs( )` font-size: 16px; margin-bottom: 16px; - padding-left: 12px; + padding-left: ${(props) => (props.level === 0 ? "0" : "12px")}; font-weight: 600; diff --git a/src/client/index.tsx b/src/client/index.tsx index e75ec6c..4e9a051 100644 --- a/src/client/index.tsx +++ b/src/client/index.tsx @@ -1,30 +1,28 @@ import React, { useEffect } from "react"; import ReactDOM from "react-dom"; import { HashRouter } from "react-router-dom"; -import Document from "./components/Document"; + +import { Document } from "./components/Document"; import { Header } from "./components/Header"; -import { StyledAside, StyledDocument, StyledMain } from "./styled"; +import { Sidebar } from "./components/Sidebar"; + import { GlobalStyle, CssVariables } from "./styled"; + import Provider from "virtual:provider"; import appData from "virtual:appData"; -import { sidebarVisible } from "./model"; const App = () => { useEffect(() => { document.title = appData.title; }, []); - const visible = sidebarVisible.use(); + return ( - -
- - - - - +
+ + ); }; diff --git a/src/client/styled/index.ts b/src/client/styled/index.ts index 7fad6d4..ee7ca91 100644 --- a/src/client/styled/index.ts +++ b/src/client/styled/index.ts @@ -1,59 +1,2 @@ -import styled from "styled-components"; export * from "./global"; export * from "./vars"; -import { Sidebar } from "../components/Sidebar"; - -export const StyledHeader = styled.header` - height: var(--header-height); - width: 100%; - background: var(--c-bg); - border-bottom: 1px solid var(--c-divider); - - display: flex; - align-items: center; - padding: 0 1rem; -`; - -export const StyledAside = styled(Sidebar)<{ visible: string }>` - padding: 1.5rem 1rem; - width: var(--sidebar-width); - height: calc(100vh - var(--header-height)); - overflow-y: auto; - display: inline-block; - border-right: 1px solid var(--c-divider); - background: white; - - @media (max-width: 768px) { - position: fixed; - left: ${(props) => - props.visible === "true" ? 0 : "calc(-1 * var(--sidebar-width))"}; - - transition: left 250ms ease-in-out; - } -`; - -export const StyledDocument = styled.div` - width: calc(100vw - var(--sidebar-width)); - height: calc(100vh - var(--header-height)); - display: inline-block; - overflow-y: auto; -`; - -export const StyledMain = styled.main` - .docit-markdown { - padding: 0 4em; - word-break: break-all; - margin-bottom: 100px; - } - - @media (max-width: 768px) { - ${StyledDocument} { - width: 100vw; - padding-left: 0rem; - } - - .docit-markdown { - padding: 0 1rem; - } - } -`; From 17e7da341eb0a516ece7c83a47ea9c137651d70c Mon Sep 17 00:00:00 2001 From: phshy0607 Date: Wed, 30 Mar 2022 18:23:27 +0800 Subject: [PATCH 07/10] feat: add `socials` to config --- docs/.docit/docit.config.js | 3 +++ src/client/components/Header/index.tsx | 1 - src/client/components/Socials/index.tsx | 36 +++++++++++++++++++++++++ src/client/components/Socials/styled.ts | 9 +++++++ src/client/components/Svgs/index.tsx | 21 +++++++++++---- src/client/components/Svgs/types.ts | 6 +++++ src/client/shim.d.ts | 6 ++++- src/node/cli.ts | 35 ++++++++++++------------ src/node/config.ts | 17 ++++++------ src/node/core/index.ts | 1 + src/node/types.ts | 33 +++++++++-------------- 11 files changed, 116 insertions(+), 52 deletions(-) create mode 100644 src/client/components/Socials/index.tsx create mode 100644 src/client/components/Socials/styled.ts create mode 100644 src/client/components/Svgs/types.ts diff --git a/docs/.docit/docit.config.js b/docs/.docit/docit.config.js index 09dafd2..9d9d176 100644 --- a/docs/.docit/docit.config.js +++ b/docs/.docit/docit.config.js @@ -3,6 +3,9 @@ import { defineConfig } from "../../src/node/index"; const config = defineConfig({ title: "Docit", publicPath: "https://phshy0607.github.io/docit/", + socials: { + Github: "https://github.com/phshy0607/docit", + }, sidebars: [ { title: "Get Started", path: "/index" }, { diff --git a/src/client/components/Header/index.tsx b/src/client/components/Header/index.tsx index 41428b1..3686c7e 100644 --- a/src/client/components/Header/index.tsx +++ b/src/client/components/Header/index.tsx @@ -4,7 +4,6 @@ import { StyledSidebarBtn, StyledTitle, StyledHeader } from "./styled"; import { setSidebarVisible, sidebarVisible } from "../../model"; import { Socials } from "../Socials"; import { Svgs } from "../Svgs"; - import appData from "virtual:appData"; const Header = () => { diff --git a/src/client/components/Socials/index.tsx b/src/client/components/Socials/index.tsx new file mode 100644 index 0000000..69febbc --- /dev/null +++ b/src/client/components/Socials/index.tsx @@ -0,0 +1,36 @@ +import React from "react"; +import { Svgs } from "../Svgs"; +import { StyledSocialContainer } from "./styled"; +import appData from "virtual:appData"; + +const defaultSvgProps = { + fill: "var(--c-black)", + width: "1.5em", + height: "1.5em", + cursor: "pointer", +}; + +const Socials = () => { + if (!appData.socials) { + return null; + } + + return ( + + {Object.entries(appData.socials).map(([key, value]) => { + const Component = Svgs[key]; + return ( + { + window.open(value, "__blank"); + }} + /> + ); + })} + + ); +}; + +export { Socials }; diff --git a/src/client/components/Socials/styled.ts b/src/client/components/Socials/styled.ts new file mode 100644 index 0000000..bc43271 --- /dev/null +++ b/src/client/components/Socials/styled.ts @@ -0,0 +1,9 @@ +import styled from "styled-components"; + +export const StyledSocialContainer = styled.div` + margin-left: auto; + + svg + svg { + margin-left: 1rem; + } +`; diff --git a/src/client/components/Svgs/index.tsx b/src/client/components/Svgs/index.tsx index 8e44471..f93a542 100644 --- a/src/client/components/Svgs/index.tsx +++ b/src/client/components/Svgs/index.tsx @@ -1,9 +1,19 @@ -import React, { SVGAttributes } from "react"; +import React from "react"; +import { SvgProps } from "./types"; -interface SvgProps extends SVGAttributes { - className?: string; - style?: React.CSSProperties; -} +const Twitter: React.FC = (props) => { + return ( + + Twitter + + + ); +}; const Github: React.FC = (props) => { return ( @@ -81,6 +91,7 @@ const AnimatedLoading: React.FC = (props) => { }; export const Svgs = { + Twitter, Github, ToggleBtn, AnimatedLoading, diff --git a/src/client/components/Svgs/types.ts b/src/client/components/Svgs/types.ts new file mode 100644 index 0000000..7cf4c20 --- /dev/null +++ b/src/client/components/Svgs/types.ts @@ -0,0 +1,6 @@ +import React, { SVGAttributes } from "react"; + +export interface SvgProps extends SVGAttributes { + className?: string; + style?: React.CSSProperties; +} diff --git a/src/client/shim.d.ts b/src/client/shim.d.ts index 40ef37a..caec863 100644 --- a/src/client/shim.d.ts +++ b/src/client/shim.d.ts @@ -35,7 +35,11 @@ declare module "virtual:routes" { declare module "virtual:appData" { const title: string; - export default { title }; + const socials: { + twitter?: string; + github?: string; + }; + export default { title, socials }; } declare module "virtual:sidebars" { diff --git a/src/node/cli.ts b/src/node/cli.ts index 22b6f0e..c1e414b 100644 --- a/src/node/cli.ts +++ b/src/node/cli.ts @@ -1,22 +1,23 @@ -import minimist from 'minimist'; -import chalk from 'chalk'; -import chokidar from 'chokidar'; -import path from 'path'; -import fsx from 'fs-extra'; -import { merge } from 'lodash-es'; -import { PKG_JSON_PATH } from './constants.js'; -import { start } from './start.js'; -import { build } from './build.js'; +import minimist from "minimist"; +import chalk from "chalk"; +import chokidar from "chokidar"; +import path from "path"; +import fsx from "fs-extra"; +import { ViteDevServer } from "vite"; +import { merge } from "lodash-es"; +import { PKG_JSON_PATH } from "./constants.js"; +import { UserConfig } from "./types.js"; +import { start } from "./start.js"; +import { build } from "./build.js"; import { isFileExists, readUserConfigFile, resolveAbsPath, -} from './utils/index.js'; -import { ViteDevServer } from 'vite'; +} from "./utils/index.js"; const argv: any = minimist(process.argv.slice(2)); const command: string = argv._[0]; -const root: string = argv._[1] || 'docs'; +const root: string = argv._[1] || "docs"; const pkg = fsx.readJSONSync(PKG_JSON_PATH); @@ -24,13 +25,13 @@ console.log(chalk.greenBright(`Running Docit@${pkg.version}`)); const configFilePath = path.resolve( resolveAbsPath(root), - './.docit/docit.config.js' + "./.docit/docit.config.js" ); let server: ViteDevServer = null; const bootstrap = () => { readUserConfigFile(configFilePath).then((userConfig) => { - if (command === 'start') { + if (command === "start") { start(merge({ root }, userConfig)) .then((s) => s.listen()) .then((s) => { @@ -38,15 +39,15 @@ const bootstrap = () => { s.printUrls(); }); } - if (command === 'build') { + if (command === "build") { build(merge({ root }, userConfig)); } }); }; -if (isFileExists(configFilePath) && command === 'start') { +if (isFileExists(configFilePath) && command === "start") { const watcher = chokidar.watch(configFilePath); - watcher.on('change', () => { + watcher.on("change", () => { if (server) { server.close(); } diff --git a/src/node/config.ts b/src/node/config.ts index e4739c4..7f6be81 100644 --- a/src/node/config.ts +++ b/src/node/config.ts @@ -1,20 +1,21 @@ -import path from 'path'; -import { isFileExists } from './utils/index.js'; -import { UserConfig, ResolvedUserConfig } from './types.js'; -import { CLIENT_PATH } from './constants.js'; +import path from "path"; +import { isFileExists } from "./utils/index.js"; +import { UserConfig, ResolvedUserConfig } from "./types.js"; +import { CLIENT_PATH } from "./constants.js"; export const resolveConfig = async ( config: UserConfig, - command: 'build' | 'start' + command: "build" | "start" ): Promise => { return { base: CLIENT_PATH, docs: path.resolve(process.cwd(), config.root), - title: config.title || 'Docit', + title: config.title || "Docit", sidebars: config.sidebars || [], providerPath: isFileExists(config.providerPath) ? config.providerPath - : path.resolve(CLIENT_PATH, './components/DefaultProvider/index.js'), - publicPath: command === 'build' ? config.publicPath : '/', + : path.resolve(CLIENT_PATH, "./components/DefaultProvider/index.js"), + publicPath: command === "build" ? config.publicPath : "/", + socials: config.socials, }; }; diff --git a/src/node/core/index.ts b/src/node/core/index.ts index f432da0..f1e6cee 100644 --- a/src/node/core/index.ts +++ b/src/node/core/index.ts @@ -213,6 +213,7 @@ class Core { private async makeAppData() { return { title: this.config.title, + socials: this.config.socials, }; } diff --git a/src/node/types.ts b/src/node/types.ts index af0dbc4..fc7bfd8 100644 --- a/src/node/types.ts +++ b/src/node/types.ts @@ -2,48 +2,41 @@ export interface UserFileConfig { title?: string; sidebars?: SidebarNode[]; publicPath?: string; + socials?: { + Twitter?: string; + Github?: string; + }; } export interface UserConfig { - /** - * docs path - * @description the path that your md/mdx file locates - */ root: string; - title?: string; - sidebars?: SidebarNode[]; - providerPath?: string; publicPath?: string; + socials?: { + Twitter?: string; + Github?: string; + }; } export interface ResolvedUserConfig { - /** - * client project location - * @description full path - */ base: string; - /** - * docs location - * @description full path - */ docs: string; - title?: string; - sidebars?: SidebarNode[]; - providerPath?: string; - publicPath?: string; + socials?: { + Twitter?: string; + Github?: string; + }; } export type DepsMapper = Map; export type DepsItem = Map< - 'default' | 'nonDefault' | 'namespace', + "default" | "nonDefault" | "namespace", Set | string >; export interface SidebarNode { From babbce76c3a78d2614913adfb495271e556a75c8 Mon Sep 17 00:00:00 2001 From: phshy0607 Date: Wed, 30 Mar 2022 18:25:35 +0800 Subject: [PATCH 08/10] feat: export types --- CHANGELOG.md | 2 ++ src/node/index.ts | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8a9e1eb..8f752b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - add `defineConfig`, to help write config file. - add `ESM` info in `ReadMe` and `docs` +- now support `socials` in `docit.config.js` file. +- export more types ## [0.6.4] - 2022-03-29 diff --git a/src/node/index.ts b/src/node/index.ts index 83b9398..6ebdf08 100644 --- a/src/node/index.ts +++ b/src/node/index.ts @@ -1,6 +1,6 @@ import { UserFileConfig } from "./types.js"; +export const defineConfig = (config: UserFileConfig) => config; export * from "./start.js"; export * from "./build.js"; - -export const defineConfig = (config: UserFileConfig) => config; +export { UserConfig } from "./types.js"; From 73dc2c90faf988915fdc83ced18501467ffc3320 Mon Sep 17 00:00:00 2001 From: phshy0607 Date: Wed, 30 Mar 2022 19:10:43 +0800 Subject: [PATCH 09/10] feat: docs --- CHANGELOG.md | 1 + README.md | 12 +- docs/.docit/docit.config.js | 67 ++++++- .../{Configs.mdx => configure/config-file.md} | 28 +-- docs/configure/provider.md | 31 ++++ .../sidebar.mdx => configure/sidebar.md} | 0 docs/configure/socials.md | 22 +++ .../static-resources.md} | 0 docs/document/MDX.md | 42 +++++ docs/document/api-generation.md | 73 ++++++++ docs/document/front-matter.md | 3 + docs/document/live-block.mdx | 75 ++++++++ docs/explaination/routes.md | 3 + docs/explaination/title.md | 3 + docs/get-started/introduction.md | 54 ++++++ docs/get-started/prerequisites.md | 1 + docs/index.mdx | 46 ----- docs/usage/Syntax.mdx | 171 ------------------ 18 files changed, 385 insertions(+), 247 deletions(-) rename docs/{Configs.mdx => configure/config-file.md} (80%) create mode 100644 docs/configure/provider.md rename docs/{usage/sidebar.mdx => configure/sidebar.md} (100%) create mode 100644 docs/configure/socials.md rename docs/{usage/static-resources.mdx => configure/static-resources.md} (100%) create mode 100644 docs/document/MDX.md create mode 100644 docs/document/api-generation.md create mode 100644 docs/document/front-matter.md create mode 100644 docs/document/live-block.mdx create mode 100644 docs/explaination/routes.md create mode 100644 docs/explaination/title.md create mode 100644 docs/get-started/introduction.md create mode 100644 docs/get-started/prerequisites.md delete mode 100644 docs/index.mdx delete mode 100644 docs/usage/Syntax.mdx diff --git a/CHANGELOG.md b/CHANGELOG.md index 8f752b9..f8fd8f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - add `ESM` info in `ReadMe` and `docs` - now support `socials` in `docit.config.js` file. - export more types +- more docs ## [0.6.4] - 2022-03-29 diff --git a/README.md b/README.md index 2bd1b1d..94b60e9 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,11 @@ - :stuck_out_tongue: MDX & MD Syntax oriented. - :tornado: Fast HMR - :chart: Out of the Box Api & Component Props Table Generation -- :heart: Emoji Support +- :heart: Emoji Support and Responsive Designs ## Get Started -This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required. +> This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required. ```sh yarn add @blizzbolts/docit -D @@ -46,5 +46,11 @@ This project is inspired by [Vitepress](https://vitepress.vuejs.org/) and [Story ## Changelog -checkout [CHANGELOG.md](https://github.com/phshy0607/docit/blob/master/CHANGELOG.md) +[CHANGELOG.md](https://github.com/phshy0607/docit/blob/master/CHANGELOG.md) + + +## Examples + +[Docit](https://phshy0607.github.io/docit/) + diff --git a/docs/.docit/docit.config.js b/docs/.docit/docit.config.js index 9d9d176..7f86eb6 100644 --- a/docs/.docit/docit.config.js +++ b/docs/.docit/docit.config.js @@ -7,24 +7,73 @@ const config = defineConfig({ Github: "https://github.com/phshy0607/docit", }, sidebars: [ - { title: "Get Started", path: "/index" }, { - title: "Usage", + title: "Get Started", children: [ { - title: "Syntax", - path: "/usage/Syntax", + title: "Introduction", + path: "/get-started/introduction", + }, + ], + }, + { + title: "Document", + children: [ + { + title: "MDX", + path: "/document/MDX", + }, + { + title: "Live Block", + path: "/document/live-block", + }, + { + title: "API Generation", + path: "/document/api-generation", + }, + { + title: "Front Matter", + path: "/document/front-matter", + }, + ], + }, + { + title: "Explaination", + children: [ + { + title: "Routes", + path: "/explaination/routes", }, { - title: "Sidebars", - path: "/usage/sidebar", + title: "Title", + path: "/explaination/title", }, - { title: "Static Resources", path: "/usage/static-resources" }, ], }, { - title: "Config File", - path: "/Configs", + title: "Configure", + children: [ + { + title: "Config File", + path: "/configure/config-file", + }, + { + title: "Sidebar", + path: "/configure/sidebar", + }, + { + title: "Provider", + path: "/configure/provider", + }, + { + title: "Static Resources", + path: "/configure/static-resources", + }, + { + title: "Socials", + path: "/configure/socials", + }, + ], }, { title: "Troubleshooting", path: "/troubleshooting" }, ], diff --git a/docs/Configs.mdx b/docs/configure/config-file.md similarity index 80% rename from docs/Configs.mdx rename to docs/configure/config-file.md index 92ffb23..4f68fa5 100644 --- a/docs/Configs.mdx +++ b/docs/configure/config-file.md @@ -67,24 +67,16 @@ const config = { { title: "FAQ", path: "/FAQ" }, { title: "Feature Request List", path: "/feature-request" }, ], -}; -export default config; -``` - -## Provider - -If you need a `Provider` to wrap the document up. You can provider a `providePath` via config file. - -For Example. -```jsx -import React from "react"; -import { ThemeProvider } from "../src/theme/Provider"; - -const Provider = (props) => { - const { children } = props; - return {children}; + /** + * Custom Social Info + * + * @Default undefined + */ + socials: { + Twitter: 'xxx', + Github: 'xxx' + } }; - -export default Provider; +export default config; ``` diff --git a/docs/configure/provider.md b/docs/configure/provider.md new file mode 100644 index 0000000..222c499 --- /dev/null +++ b/docs/configure/provider.md @@ -0,0 +1,31 @@ + +# Provider + +If you need a `Provider` to wrap the document up. You can provider a `providePath` via config file. + + +## Example + +```js +// docit.config.js +import { resolve } from 'path' + +export default { + providerPath: resolve(__dirname, '../../Provder/index.jsx') +} +``` + + +```jsx +// Provider/index.jsx + +import React from "react"; +import { ThemeProvider } from "../src/theme/Provider"; + +const Provider = (props) => { + const { children } = props; + return {children}; +}; + +export default Provider; +``` \ No newline at end of file diff --git a/docs/usage/sidebar.mdx b/docs/configure/sidebar.md similarity index 100% rename from docs/usage/sidebar.mdx rename to docs/configure/sidebar.md diff --git a/docs/configure/socials.md b/docs/configure/socials.md new file mode 100644 index 0000000..ea0e038 --- /dev/null +++ b/docs/configure/socials.md @@ -0,0 +1,22 @@ +# Socials + +add a `socials` object in your `docit.config.js` file + +> Checkout [Config File](#/configure/config-file) for Config file setup + +Currently only support `Twitter` and `Github` + +Your social info will displayed at the right side of header + + +## Example + +```js +// docit.config.js + +export default { + socials: { + Github: 'https://github.com/phshy0607/docit' + } +} +``` diff --git a/docs/usage/static-resources.mdx b/docs/configure/static-resources.md similarity index 100% rename from docs/usage/static-resources.mdx rename to docs/configure/static-resources.md diff --git a/docs/document/MDX.md b/docs/document/MDX.md new file mode 100644 index 0000000..a1007ce --- /dev/null +++ b/docs/document/MDX.md @@ -0,0 +1,42 @@ +# MDX + +MDX is a syntax that enable writing JSX and JavaScript expressions in your Markdown files. + + +## Syntax + +```md +# Title 1 + +## Title 2 + +{ console.log({str: 'hello world!'})} + +export const MyComponent = () => Coffee Time + + +``` + +Check out [MDX](https://mdxjs.com/docs/what-is-mdx/) for more. + + +## Usage + +Docit support normal `.md` files by default. + +To render components in Markdown file, please use `.mdx` as file extension. + +You can mix and layout your files as you want. + +For Example + +```md +|- docs + |- get-started + |- introduction.md + |- features.md + |- components + |- Button.mdx + |- Sidebar.mdx +|- package.json +``` \ No newline at end of file diff --git a/docs/document/api-generation.md b/docs/document/api-generation.md new file mode 100644 index 0000000..641b4c1 --- /dev/null +++ b/docs/document/api-generation.md @@ -0,0 +1,73 @@ +# API Generation + +Docit provides a simple syntax to handle auto API parsing. + +> Currently only support React Typescript API Tables. Functions and Interface support might not work as you expected. + +### Syntax + +```md +[Props](../components/Button.tsx) +``` + +Inside Docit, it will check the text name to be `Props` and resolve your component path using [resolve](https://www.npmjs.com/package/resolve) + +For Example + +```jsx +import React from "react"; +import styled from "styled-components"; + +enum Length { + /** + * Large + */ + Large = 5, + /** + * 中 + */ + Medium = 3, + /** + * 小 + */ + Small = 1, +} + +interface ButtonProps extends HTMLButtonElement { + /** + * 一种颜色 + * @default red + */ + color?: string; + length: Length; +} + +export const StyledButton = styled.button` + z-index: 9999; +`; + +const Button: React.FC = () => { + return 1; +}; + +Button.defaultProps = { + color: "green", + length: Length.Large, +}; + +export { Button }; +``` + +The API table will look like: + +[Props](../components/ApiTest.tsx) + +You will notice `StyledButton` get exported, but the api table does not appear, thats because the type parser got nothing from parsing it. + +--- + +since Docit using `resolve`, you can actually parsing some third party types like + +```md +[Props](antd-mobile/es/index.d.ts) +``` diff --git a/docs/document/front-matter.md b/docs/document/front-matter.md new file mode 100644 index 0000000..6404765 --- /dev/null +++ b/docs/document/front-matter.md @@ -0,0 +1,3 @@ +# Front Matter + +WIP \ No newline at end of file diff --git a/docs/document/live-block.mdx b/docs/document/live-block.mdx new file mode 100644 index 0000000..4fc72fd --- /dev/null +++ b/docs/document/live-block.mdx @@ -0,0 +1,75 @@ +# Live Block + +Live Block is a way to speed up your doc writing by rendering and showing code at the same time. + +Just add `live` keyword after code block language + +Docit only respect `live` keyword for `js` `jsx` `ts` and `tsx` languages + +> The code you writing is rendered in a sandbox(iframe), and also a JavaScript sandbox (serving as an independent dynamic import). + +### Syntax + +````md +```jsx live +import { DemoBlock } from "../components/DemoBlock"; +; +``` +```` + +This will render as + +```jsx live +import { DemoBlock } from "../components/DemoBlock"; +; +``` + +### Why? + +Markdown naturally has code block syntax + +For Example: + +````md +```jsx +import { DemoBlock } from "../components/DemoBlock"; +; +``` +```` + +Your markdown might look like + +````md +import { DemoBlock } from "../components/DemoBlock"; + +; + +```jsx +import { DemoBlock } from "../components/DemoBlock"; +; +``` +```` + +You will find that you write the statement twice. + +And if your code has changes, you need to apply the changes twice. + +## For Mobile + +### Syntax + +````md +```jsx live mobile +import { DemoBlock } from "../components/DemoBlock"; +; +``` +```` + +Docit also support live mobile block. Add a `mobile` keyword after `live` to enable it. + +```jsx live mobile +import { DemoBlock } from "../components/DemoBlock"; +; +``` + +Docit provides a `360 * 640` mobile view to help you display responsive component diff --git a/docs/explaination/routes.md b/docs/explaination/routes.md new file mode 100644 index 0000000..fc52a27 --- /dev/null +++ b/docs/explaination/routes.md @@ -0,0 +1,3 @@ +# Routes + +WIP \ No newline at end of file diff --git a/docs/explaination/title.md b/docs/explaination/title.md new file mode 100644 index 0000000..79acb4f --- /dev/null +++ b/docs/explaination/title.md @@ -0,0 +1,3 @@ +# Title + +WIP \ No newline at end of file diff --git a/docs/get-started/introduction.md b/docs/get-started/introduction.md new file mode 100644 index 0000000..75b18b1 --- /dev/null +++ b/docs/get-started/introduction.md @@ -0,0 +1,54 @@ +# Docit + +> Simple and Rapid React Documentation https://phshy0607.github.io/docit + +- :stuck_out_tongue: MDX & MD Syntax oriented. +- :tornado: Fast HMR +- :chart: Out of the Box Api & Component Props Table Generation +- :heart: Emoji Support and Responsive Designs + +## Get Started + +> This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required. + +```sh +yarn add @blizzbolts/docit -D +``` + +### Usage + +1. Make your first markdown file under `docs` + +```sh +mkdir docs + +echo "# Introudction" > docs/index.md +``` + +2. Start your doc local dev server by + +```sh +docit start +``` + +For build + +```sh +docit build +``` + +## Credits + +This project is inspired by [Vitepress](https://vitepress.vuejs.org/) and [Storybook](https://storybook.js.org/), powered by [Vite](https://vitejs.dev/) and [MDX](https://mdxjs.com/) + + +## Changelog + +[CHANGELOG.md](https://github.com/phshy0607/docit/blob/master/CHANGELOG.md) + + +## Examples + +[Docit](https://phshy0607.github.io/docit/) + + diff --git a/docs/get-started/prerequisites.md b/docs/get-started/prerequisites.md new file mode 100644 index 0000000..ef22268 --- /dev/null +++ b/docs/get-started/prerequisites.md @@ -0,0 +1 @@ +# Prerequisites \ No newline at end of file diff --git a/docs/index.mdx b/docs/index.mdx deleted file mode 100644 index 232d8ee..0000000 --- a/docs/index.mdx +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Introduction ---- - -# Docit - -> Simple and Rapid React Documentation - -- :stuck_out_tongue: MDX & MD Syntax oriented. -- :tornado: Fast HMR -- :chart: Out of the Box Api & Component Props Table Generation -- :heart: Emoji Support - -## Install - -This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required. - -```sh -yarn add @blizzbolts/docit -D -``` - -### Get Started - -1. Make your first markdown file under `docs` - -```sh -mkdir docs - -echo "# Introudction" > docs/index.md -``` - -2. Start your doc local dev server by - -```sh -docit start -``` - -For build - -```sh -docit build -``` - -## Usage - -Checkout [Syntax](#/usage/syntax) diff --git a/docs/usage/Syntax.mdx b/docs/usage/Syntax.mdx deleted file mode 100644 index 5ed3d58..0000000 --- a/docs/usage/Syntax.mdx +++ /dev/null @@ -1,171 +0,0 @@ -# Syntax - -Docit is a MDX & MD oriented document tool. - -It's based on MDX and MD syntax, and support with some others to fit your needs. - -## MDX - -MDX is a syntax that enable writing JSX and JavaScript expressions in your Markdown files. - -```md -# Title 1 - -## Title 2 - -{ console.log({str: 'hello world!'})} - -export const MyComponent = () => Coffee Time - - -``` - -Check out [MDX](https://mdxjs.com/docs/what-is-mdx/) for more. - -## Live Block - -Live Block is a way to speed up your doc writing by rendering and showing code at the same time. - -Just add `live` keyword after code block language - -> The code you writing is rendered in a sandbox(iframe), and also a JavaScript sandbox (serving as an independent dynamic import). - -### Syntax - -````md -```jsx live -import { DemoBlock } from "../components/DemoBlock"; -; -``` -```` - -This will render as - -```jsx live -import { DemoBlock } from "../components/DemoBlock"; -; -``` - -### Why? - -Markdown naturally has code block syntax - -For Example: - -````md -```jsx -import { DemoBlock } from "../components/DemoBlock"; -; -``` -```` - -Your markdown might look like - -````md -import { DemoBlock } from "../components/DemoBlock"; - -; - -```jsx -import { DemoBlock } from "../components/DemoBlock"; -; -``` -```` - -You will find that you write the statement twice. - -And if your code has changes, you need to apply the changes twice. - -## Mobile View - -### Syntax - -````md -```jsx live mobile -import { DemoBlock } from "../components/DemoBlock"; -; -``` -```` - -Docit also support live mobile block. Add a `mobile` keyword after `live` to enable it. - -```jsx live mobile -import { DemoBlock } from "../components/DemoBlock"; -; -``` - -Docit provides a `360 * 640` mobile view to help you display responsive component - -## API Generation - -Docit provides a simple syntax to handle auto API parsing. - -> Currently only support React Typescript API Tables. Functions and Interface support might not work as you expected. - -### Syntax - -```md -[Props](../components/Button.tsx) -``` - -Inside Docit, it will check the text name to be `Props` and resolve your component path using [resolve](https://www.npmjs.com/package/resolve) - -For Example - -```jsx -import React from "react"; -import styled from "styled-components"; - -enum Length { - /** - * Large - */ - Large = 5, - /** - * 中 - */ - Medium = 3, - /** - * 小 - */ - Small = 1, -} - -interface ButtonProps extends HTMLButtonElement { - /** - * 一种颜色 - * @default red - */ - color?: string; - length: Length; -} - -export const StyledButton = styled.button` - z-index: 9999; -`; - -const Button: React.FC = () => { - return 1; -}; - -Button.defaultProps = { - color: "green", - length: Length.Large, -}; - -export { Button }; -``` - -The API table will look like: - -[Props](../components/ApiTest.tsx) - -You will notice `StyledButton` get exported, but the api table does not appear, thats because the type parser got nothing from parsing it. - ---- - -since Docit using `resolve`, you can actually parsing some third party types like - -```md -[Props](antd-mobile/es/index.d.ts) -``` From f32dfbe9ed6bb1eada27972b882a194918fb749d Mon Sep 17 00:00:00 2001 From: phshy0607 Date: Wed, 30 Mar 2022 19:10:58 +0800 Subject: [PATCH 10/10] chore: update version --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index a341cb5..798cf5a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@blizzbolts/docit", - "version": "0.6.4", + "version": "0.6.5", "license": "MIT", "bin": { "docit": "bin/docit.js"