From d0ff5c986e0061f5a0a906be0ba9ef8904122f77 Mon Sep 17 00:00:00 2001 From: Ahad Birang Date: Thu, 25 Feb 2021 02:00:34 +0330 Subject: [PATCH] feat: detect title and description of document (#98) * feat: detect title and description of document * chore: update markdown files --- docs/content/1.index.md | 6 ++-- docs/content/2.installation.md | 6 ++-- docs/content/2.usage/1.configuration.md | 3 +- docs/content/2.usage/2.content.md | 3 +- docs/content/2.usage/3.components.md | 3 +- docs/content/2.usage/4.assets.md | 3 +- docs/content/2.usage/5.template.md | 3 +- docs/content/3.more/1.example.md | 6 ++-- docs/content/3.more/2.showcases.md | 3 +- docs/content/3.more/3.deployment.md | 6 ++-- docs/content/3.more/4.migration.md | 6 ++-- theme/module.js | 4 ++- theme/utils/document.js | 44 +++++++++++++++++++++++++ 13 files changed, 79 insertions(+), 17 deletions(-) diff --git a/docs/content/1.index.md b/docs/content/1.index.md index 68f652c3b..5ff9f58f4 100644 --- a/docs/content/1.index.md +++ b/docs/content/1.index.md @@ -1,7 +1,5 @@ --- -title: Introduction category: Getting Started -description: 'Create beautiful documentations with Markdown, Vue and TailwindCSS ✨' features: - Powered by Markdown - Ready for translations @@ -13,6 +11,10 @@ features: - Static Generated --- +# Introduction + +> Create beautiful documentations with Markdown, Vue and TailwindCSS ✨ + Docus makes it easy to create beautiful documentation, it is using [Vue](https://vuejs.org), [Nuxt](https://nuxtjs.org), [Content](https://content.nuxtjs.org) and [TailwindCSS](https://tailwindcss.com) under the hood. Create a new docs with our [GitHub template](/installation#github-template) or [locally](/installation#download-locally) and start writing markdown in a beautiful documentation, live preview your changes and use [Vue components](/usage/components). diff --git a/docs/content/2.installation.md b/docs/content/2.installation.md index 250c27912..6f1ae12e9 100644 --- a/docs/content/2.installation.md +++ b/docs/content/2.installation.md @@ -1,9 +1,11 @@ --- -title: Installation -description: 'Setting up a beautiful documentation with Docus is one command away 🤙' category: Getting Started --- +# Installation + +> Setting up a beautiful documentation with Docus is one command away 🤙 + Docus is a pre-configured [Nuxt](https://nuxtjs.org) application, with [TailwindCSS](https://tailwindcss.com) and [Nuxt Content](https://content.nuxtjs.org). ## System Requirements diff --git a/docs/content/2.usage/1.configuration.md b/docs/content/2.usage/1.configuration.md index 1f4dc6f7d..6c9ce0ca1 100644 --- a/docs/content/2.usage/1.configuration.md +++ b/docs/content/2.usage/1.configuration.md @@ -1,8 +1,9 @@ --- -title: Configuration category: Usage --- +# Configuration + ## Theme You can create a `content/settings.json` file to configure the theme. diff --git a/docs/content/2.usage/2.content.md b/docs/content/2.usage/2.content.md index aa37ec4bb..3442da58c 100644 --- a/docs/content/2.usage/2.content.md +++ b/docs/content/2.usage/2.content.md @@ -1,9 +1,10 @@ --- -title: Writing content for the docs menuTitle: Content category: Usage --- +# Writing content for the docs + Once you've setup your documentation, you can directly start writing your content. diff --git a/docs/content/2.usage/3.components.md b/docs/content/2.usage/3.components.md index 5c1d23751..c4f2d3d32 100644 --- a/docs/content/2.usage/3.components.md +++ b/docs/content/2.usage/3.components.md @@ -1,9 +1,10 @@ --- -title: Components menuTitle: Components category: Usage --- +# Components + The theme comes with some default Vue.js components you can use directly in your markdown content. > You can create your own components in the `components/global/` folder, check out [this section](https://content.nuxtjs.org/writing#vue-components). diff --git a/docs/content/2.usage/4.assets.md b/docs/content/2.usage/4.assets.md index b7033a7d1..a3a37f73b 100644 --- a/docs/content/2.usage/4.assets.md +++ b/docs/content/2.usage/4.assets.md @@ -1,9 +1,10 @@ --- -title: Assets menuTitle: Assets category: Usage --- +# Assets + ## Favicon and PWA Icon You can add a `static/icon.png` image to enable [nuxt-pwa](https://pwa.nuxtjs.org) and generate a favicon automatically. diff --git a/docs/content/2.usage/5.template.md b/docs/content/2.usage/5.template.md index cab148d8c..fc5594b5a 100644 --- a/docs/content/2.usage/5.template.md +++ b/docs/content/2.usage/5.template.md @@ -1,9 +1,10 @@ --- -title: Template menuTitle: Template category: Usage --- +# Template + ## Slots Docus support customizable slots in the template. You can use this slots to show custom information. In order to show information in one of slots, you need to create a component inside `components` directory with the same name. diff --git a/docs/content/3.more/1.example.md b/docs/content/3.more/1.example.md index 76957b288..30ca2e890 100644 --- a/docs/content/3.more/1.example.md +++ b/docs/content/3.more/1.example.md @@ -1,9 +1,11 @@ --- -title: Example category: More -description: 'Live example of Nuxt Content docs theme on CodeSandbox.' csb_link: https://codesandbox.io/embed/docus-starter-1xsm7?hidenavigation=1&theme=dark fullscreen: true --- +# Example + +> Live example of Nuxt Content docs theme on CodeSandbox. + diff --git a/docs/content/3.more/2.showcases.md b/docs/content/3.more/2.showcases.md index c354666f6..eb9d38bfb 100644 --- a/docs/content/3.more/2.showcases.md +++ b/docs/content/3.more/2.showcases.md @@ -1,5 +1,4 @@ --- -title: Showcases category: More fullscreen: true showcases: @@ -21,4 +20,6 @@ showcases: - https://speedcurve.nuxtjs.org --- +# Showcases + diff --git a/docs/content/3.more/3.deployment.md b/docs/content/3.more/3.deployment.md index c113062a1..84afc9d2c 100644 --- a/docs/content/3.more/3.deployment.md +++ b/docs/content/3.more/3.deployment.md @@ -1,9 +1,11 @@ --- -title: Deployment category: More -description: 'Deploy your documentation with Docus to any static hosting 🪶' --- +# Deployment + +> Deploy your documentation with Docus to any static hosting 🪶 + To generate the documentation for production, run the following command: diff --git a/docs/content/3.more/4.migration.md b/docs/content/3.more/4.migration.md index 5dbc53e47..38ad1e2d9 100644 --- a/docs/content/3.more/4.migration.md +++ b/docs/content/3.more/4.migration.md @@ -1,10 +1,12 @@ --- -title: Migrate from @nuxt/content-theme-docs menuTitle: Migration category: More -description: 'Migrate from @nuxt/content-theme-docs to Docus' --- +# Migrate from @nuxt/content-theme-docs + +> Migrate from @nuxt/content-theme-docs to Docus + By migrating to docus, you will have a fresh new design for your documentation ✨
diff --git a/theme/module.js b/theme/module.js index 09b71f854..a93465500 100644 --- a/theme/module.js +++ b/theme/module.js @@ -3,7 +3,7 @@ import defu from 'defu' import gracefulFs from 'graceful-fs' import tailwindConfig from './tailwind.config' -import { generatePosition, generateSlug, isDraft } from './utils/document' +import { generatePosition, generateSlug, isDraft, processDocumentInfo } from './utils/document' const fs = gracefulFs.promises const r = (...args) => resolve(__dirname, ...args) @@ -91,6 +91,8 @@ export default function docusModule () { const _to = `${_dir}/${slug}`.replace(/\/+/, '/') const position = generatePosition(_to, document) + processDocumentInfo(document) + document.slug = generateSlug(slug) document.position = position document.to = generateSlug(_to) diff --git a/theme/utils/document.js b/theme/utils/document.js index 63df3bf02..b72ba4cf9 100644 --- a/theme/utils/document.js +++ b/theme/utils/document.js @@ -20,6 +20,50 @@ export function isDraft (path) { return !!path.match(/(\.draft)$/, '$2') } +export function processDocumentInfo (document) { + if (document.title && document.description) { + return document + } + const [first, second] = document.body.children + .flatMap(node => node.children ? node.children : node) + // top level `text` can be ignored + .filter(node => node.type !== 'text') + + if (first && first.tag === 'h1') { + if (!document.title) { + document.title = getTextContent(first) + Object.assign(first, { + type: 'text', value: '' + }) + } + // look for second element to find description + if (second && second.tag === 'blockquote') { + if (!document.description) { + document.description = getTextContent(second) + Object.assign(second, { + type: 'text', value: '' + }) + } + } + } else if (first && first.type === 'blockquote') { + if (!document.description) { + document.description = getTextContent(first) + Object.assign(first, { + type: 'text', value: '' + }) + } + } + return document +} + +function getTextContent (node) { + let text = node.value || '' + if (node.children) { + text = text + node.children.map(child => getTextContent(child)).join('') + } + return text +} + function paddLeft (value, length) { return ('0'.repeat(length) + value).substr(String(value).length) }