Skip to content

Commit

Permalink
fix: do not extract heading from content (#506)
Browse files Browse the repository at this point in the history
* fix: do not extract heading from content

* fix: update shortcuts

* fix: remove anchor link from H1 tag

* ✨ (extraction) update content and fix styling

Co-authored-by: Yaël GUILLOUX <yael.guilloux@gmail.com>
  • Loading branch information
farnabaz and Tahul authored Jun 23, 2021
1 parent e768e1e commit d508213
Show file tree
Hide file tree
Showing 26 changed files with 136 additions and 152 deletions.
2 changes: 2 additions & 0 deletions docs/content/1.get-started/1.installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Setting up a beautiful website with Docus is one command away. 🤙

---

Docus is an opinionated [Nuxt](https://nuxtjs.org) application that allows you to generate **content-based websites** with ease.

## System Requirements
Expand Down
2 changes: 2 additions & 0 deletions docs/content/1.get-started/2.configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Tailor Docus for your own identity easily. 🌈

---

## Website

You need to create a `docus.config.js` file to configure the website.
Expand Down
2 changes: 2 additions & 0 deletions docs/content/2.writing/1.my-first-page.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ navigation:

The fastest path to writing your content. 🏎

---

Let's walk through the creation of a simple introduction page.

## Create the file
Expand Down
4 changes: 3 additions & 1 deletion docs/content/2.writing/2.syntax.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Docus syntax makes you love your components even more. 🤝

---

Docus writing experience is based on a specific syntax built upon Vue components.

It enables you to write **inline** and **block** components straight from your Markdown files.
Expand Down Expand Up @@ -356,4 +358,4 @@ Other that spans the attribute syntax will work on images, links, `code`, **bold
[link](#attributes){.bg-primary-400}, `code`{style="color: tomato"},
_italic_{.bg-primary-500} and **bold**{.bg-primary-500} texts.
::
::
::
2 changes: 2 additions & 0 deletions docs/content/2.writing/3.front-matter.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Easily configure the rendering of your Markdown pages. 📝

---

Front-matter is used to transmit data to your components and templates, from any page or directory.

## Native parameters
Expand Down
2 changes: 2 additions & 0 deletions docs/content/2.writing/4.prose.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Customizing your Markdown rendering has never been easier. 🧙‍♂️

---

Docus Markdown rendering preserves the HTML structure of your file.

We are using a per-tag component system that allows you to customize your Markdown rendering per HTML tag.
Expand Down
4 changes: 3 additions & 1 deletion docs/content/3.features/1.routing.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

A good looking website from any directory. 🔮

---

Each markdown page in the `contentDir` directory will become a page and will be listed in the left navigation.

You can also put your markdown files in nested directories to generate nested routes.
Expand Down Expand Up @@ -75,4 +77,4 @@ content/

::alert
**Note**: The beginning `_` will remove from document path, and you don't need to use `_` in search queries.
::
::
2 changes: 2 additions & 0 deletions docs/content/3.features/2.localization.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Enable i18n just by creating a directory. 🗺

---

The first level of directories in the `content/` folder are the locales used with [nuxt-i18n](https://github.com/nuxt-community/i18n-module) as defined in your `nuxt.config.js`.

If no `en` directory is specified, all the files inside `content/` will be considered as **English**:
Expand Down
2 changes: 2 additions & 0 deletions docs/content/3.features/3.assets.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Easily import and optimize your assets with pre-defined modules. 🙈

---

## 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.
Expand Down
2 changes: 2 additions & 0 deletions docs/content/3.features/4.social-image.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Docus automatically generates a social preview image for every document. 🤳

---

It uses the `social-image-preview` page to generate the images.

If you want to customize social images for your documentation, create `social-image-preview.vue` inside `pages` directory and design your image.
Expand Down
2 changes: 2 additions & 0 deletions docs/content/3.features/5.deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Deploy your documentation with Docus to any static hosting. 🪶

---

To generate the documentation for production, run the following command:

::code-group
Expand Down
2 changes: 2 additions & 0 deletions docs/content/3.features/6.extend.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Extend Docus with the power of Nuxt modules. 🚀

---

Docus is based on Nuxt, so you can benefit from the existing ecosystem of [Nuxt Modules](https://modules.nuxtjs.org/).

## Analytics
Expand Down
2 changes: 2 additions & 0 deletions docs/content/3.features/7.migration.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ navigation:

Migrate from @nuxt/content-theme-docs to Docus. 🔋

---

By migrating to Docus, you will have a fresh new design for your documentation :sparkles:

<div class="flex flex-wrap">
Expand Down
2 changes: 2 additions & 0 deletions docs/content/4.theme/1.settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ navigation:

The default theme is entirely customizable, from a simple configuration file! ✨

---

The default configuration sets defaults for every needed feature of your theme.

::code-group
Expand Down
2 changes: 2 additions & 0 deletions docs/content/4.theme/2.components.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Good looking components, ready to use in your website. 💄

---

Docus default theme comes with a lot of pre-defined components.

## `alert`
Expand Down
2 changes: 2 additions & 0 deletions docs/content/4.theme/5.layout.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Customize your website with slots or overwrite the layout components. 🧩

---

With the power of the [Nuxt Components](https://github.com/nuxt/components#overwriting-components), every part of the template is fully customizable.

Overwriting a component is simple as creating a new component.
Expand Down
2 changes: 2 additions & 0 deletions docs/content/4.theme/6.slots.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Docus supports customizable slots in the template. 🧱

---

Just create a component inside your `components` directory with the same name as the slot.

For example to overwrite the `<AsideTop>` slot, create `components/AsideTop.vue`:
Expand Down
1 change: 0 additions & 1 deletion docs/content/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ description: >-
Write pages in markdown, use Vue components, add style with Windi CSS and enjoy the power of Nuxt with a blazing fast developer experience.
template: page
navigation: false
# layout
layout.asideClass: 'block lg:hidden'
layout.aside: true
---
Expand Down
12 changes: 9 additions & 3 deletions src/core/module.ts
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
import { resolve, join } from 'path'
import gracefulFs from 'graceful-fs'
import { pascalCase } from 'scule'
import { Module } from '@nuxt/types'
import hash from 'hasha'
import mkdirp from 'mkdirp'
import { DocusDocument, ParserOptions } from '../types'
import { generatePosition, generateSlug, generateTo, isDraft, isHidden, processDocumentInfo } from './utils/document'
import { generatePosition, generateSlug, generateTo, isDraft, isHidden } from './utils/document'
import { destroyStorage, initStorage, useNuxtIgnoreList } from './storage'
import { destroyDB, useDB } from './database'
import { createServerMiddleware } from './server'
Expand Down Expand Up @@ -83,8 +84,6 @@ export default <Module>async function docusModule() {
const _to = `${_dir}/${slug}`.replace(/\/+/, '/')
const position = generatePosition(_to, document)

processDocumentInfo(document)

/**
* Disable document navigation if it is marked as `page = false`
* This will prevent showing non-pages in navigation menus
Expand All @@ -106,6 +105,13 @@ export default <Module>async function docusModule() {
document.path = document.to
document.language = _language
document.draft = document.draft || isDraft(slug)

/**
* Generate title from page slug
*/
if (!document.title) {
document.title = document.to.split('/').pop().split(/[\s-]/g).map(pascalCase).join(' ')
}
})

// Initiate storage
Expand Down
14 changes: 10 additions & 4 deletions src/core/parser/markdown/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,10 @@ import defu from 'defu'
import { MarkdownParserOptions, Toc } from '../../../types'
import { processOptions } from './utils'
import { generateToc } from './toc'
import { generateBody, generateDescription } from './content'
import { generateBody } from './content'
import propsDirective from './directive/props'
import { parse as parseFrontMatter } from './fontmatter'
import { processHeading } from './meta'

const DEFAULTS: MarkdownParserOptions = {
toc: {
Expand Down Expand Up @@ -44,14 +45,19 @@ async function parse(file, options) {
}

let excerpt
let description
if (rest.excerpt) {
excerpt = await generateBody(rest.excerpt, { ...options, data })
description = generateDescription(excerpt)
}

/**
* Process content headeings
*/
const heading = processHeading(body)

return {
description,
...data,
title: data.title || heading.title,
description: data.description || heading.description,
toc,
body,
text: file,
Expand Down
74 changes: 74 additions & 0 deletions src/core/parser/markdown/meta.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
import defu from 'defu'
import { expandTags, flatUnwrap, nodeTextContent } from '../../runtime/utils'
import { DocusRootNode } from '../../../types'

export function processHeading(body: DocusRootNode) {
let title = ''
let description = ''
const children = body.children
// top level `text` can be ignored
.filter(node => node.type !== 'text')

if (children.length && expandTags(['h1']).includes(children[0].tag)) {
/**
* Remove node
*/
const node = children.shift()

/**
* Remove anchor link from H1 tag
*/
node.children = flatUnwrap(node.children, ['a'])

/**
* Generate title
*/
title = nodeTextContent(node)

/**
* Inject class
*/
node.props = defu(node.props, {
class: 'd-heading-title'
})
}

if (children.length && expandTags(['p']).includes(children[0].tag)) {
/**
* Remove node
*/
const node = children.shift()

/**
* Generate description
*/
description = nodeTextContent(node)

/**
* Inject class
*/
node.props = defu(node.props, {
class: 'd-heading-description'
})
}

if (children.length && expandTags(['hr']).includes(children[0].tag)) {
/**
* Remove node
*/
const node = children.shift()

/**
* Inject class
*/
node.props = defu(node.props, {
class: 'd-heading-hr'
})
}

return {
title,
description,
body
}
}
1 change: 1 addition & 0 deletions src/core/runtime/utils.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ export const TAGS_MAP = {
h4: ['h4', 'prose-h4'],
h5: ['h5', 'prose-h5'],
h6: ['h6', 'prose-h6'],
hr: ['hr', 'prose-hr'],
p: ['p', 'prose-paragraph'],
ul: ['ul', 'prose-ul'],
ol: ['ol', 'prose-ol'],
Expand Down
Loading

1 comment on commit d508213

@vercel
Copy link

@vercel vercel bot commented on d508213 Jun 23, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.