nuxt-themes/docus

Write beautiful documentations with Nuxt and Markdown.

Docus

Docus is the fastest way to create document-driven websites with Vue & Markdown.

• 📄 Documentation
• ⚡️ Play on StackBlitz

Start a project with Docus

You can use this template to create a new project.

If you want to add Docus to an existing codebase, you can do so with:

• Install the dependency:

npm install @nuxt-themes/docus

• Add it to your extends key in nuxt.config:

defineNuxtConfig({
  extends: '@nuxt-themes/docus'
})

Features ✨

• +50 Components ready to build rich pages
• Article, Docs and Blog layouts
• Start from a README, scale to a framework documentation
• Table of contents support
• Configurable design system integration
• Replace, extend, customize any component in a breeze
• Leverages @nuxt-themes/typography
• Used on Content Documentation

They are using it 🎨

• nuxt/http
• nuxt/content
• nuxt/image
• nuxt-modules/tailwindcss
• nuxt-modules/strapi
• nuxt-modules/sanity
• nuxt-modules/i18n
• nuxt-modules/color-mode
• nuxt-modules/apollo
• nuxt-community/ackee-module
• hubble-exchange/docs
• sidebase
• haraka
• pinia-orm
• nuxt-typed-router
• Do you use Docus? Get listed here!

Contributing 🙏

1. Clone this repository
2. Install dependencies using pnpm install --frozen-lockfile
3. Run pnpm run prepare to generate type stubs.
4. Use pnpm run dev to start default starter. You can edit the module because pnpm workspace links it with the default starter.
5. Do not commit any change in .starters/default since its your playground.

License 📎

MIT License

docus's Issues

Not search on mobile

The search bar is not visible on docus.dev on mobile

GitHub Template for starter

nuxt/docus-starter

Comment from @Atinux:

Use degit for quick start

degit nuxt/docus-starter docs

Embed Tweets with great performances

It would be great to embed tweet without having to use Twitter script and loose performances.

A great example I have seen is on https://leerob.io/tweets

In order to work, I think a remark plugin would be best, see how Gatsby is doing with https://www.gatsbyjs.com/plugins/@weknow/gatsby-remark-twitter/

Otherwise, I see that Lee Rob uses the Twitter API:

• Tweet component
• getTweets(ids)
• Usage in pages/tweets.js

Fix dropdown component

Add the new `github` setting in the migration guide

Improve active link on Table of Contents

It feels quite off sometimes, ex: https://strapi.nuxtjs.org/setup

See Tailwind example: https://tailwindcss.com/docs/installation#add-tailwind-as-a-post-css-plugin

Integrate DocSearch

Upgrade to Tailwind 2

nuxt/nuxt#8546

Add Analytics section

Link to Nuxt modules to add Analytics, example with plausible module and another one with using Head

Support page level layout

See https://www.github.com/nuxt/nuxt.js/issues/3510#issuecomment-736757419

Document how to overwrites components

We should explain how to extend the components (Sidebar, Header, Footer).

Related to nuxt/content#328

Deployment section

• Netlify
• Vercel
• GitHub pages (with action)
• Gitlab Pages
• Surge.sh

Make `en` directory optional

I think it would be great to support having to locale dir by default to avoid too many levels.

content/
  index.md

Rename title to name

In settings.json + add backward compability with title

Lighthouse score 💯

Best to use on private window on Chrome

Fix remark prose plugin to detect vue components

The plugin detects components based node type in their AST representation. But AST node may differ for a single component.

{  
  type: 'paragraph',
  children: [
    {
      type: 'html',
      value: '<external-link href="https://github.com/nuxtlabs/docus-starter/generate">',
      position: [Object]
    },
    {
      type: 'text',
      value: 'Create a repo with the Docus starter',
      position: [Object]
    },
    {
      type: 'html',
      value: '</external-link>',
      position: [Object]
    }
  ]
}

Paragraph nodes with html child should unwrap. https://github.com/nuxt/content/blob/dev/packages/content/parsers/markdown/handlers/paragraph.js

feat: mermaid integration

See nuxt/content#746 (comment)

Docs: Fix logo on on Assets

See https://docus.dev/assets

feat: netlify template

• https://templates.netlify.com/
• Deploy on Netlify button

Github Pages deployment

Create draft document for Docus deployment on Github Pages using Github Actions

Yaml/Markdown hightlight code

When app is generated, trailing slash is breaking the active selected menu

feat: vercel template

• https://vercel.com/new/templates
• Deploy on Vercel button

Menu Ordering

Is your feature request related to a problem? Please describe.

Currently it is so hard to maintain order menu items since we need position for each content which makes refactoring hard without using

Describe the solution you'd like

Idea 1:

• Support categoryPosition
• Set relative position per category

Idea 2:

• Define outline (categories with order) inside docus settings

Idea 3: (preferred)

Similar to (1) but use file directory prefix (content/en/1.deploy/2.vercel.md)

Side note: Also would be nice if by default using alphabetical sorting currently seems not happening

Fix overflow on prev/next

Move store to $docus

Remove hash icon on titles for mobile

I think they should be more like vuejs.org where we can click on the title instead.

Code formatting

Version

nuxt:
docus: 0.0.4

Reproduction Link

• https://http.nuxtjs.org/hooks
• https://github.com/nuxt/http/tree/master/docs

Steps to reproduce

What is Expected?

Code formatting happening for headers and alert box

What is actually happening?

[imporant] nuxt 2.15 support

nuxt: 2.15
docus: 0.0.7

Ref: nuxt/image#186

With nuxt 2.15 using components v2, we prefix components by their full path instead of one level. This breaks docus. atoms, icons and molecules dirs explicitly added but organisms and templates are missing

Better support plugins

Related also to nuxt/content#746

It would be nice to directly support using ~/@ in plugins, css, components options.

Since ~ is an alias of srcDir but docus overwrites it to its own dir, we shall go throught the user defined keys to replace ~ with ~~ and @ to @@ (or directly replace using rootDir).

cc @pi0, what do you think?

Apply theme-docs merged PRs

• nuxt/content#690
• nuxt/content#687
• nuxt/content#722
• nuxt/content#739

Colorizing diff syntax

Is your feature request related to a problem? Please describe.

Sometimes in docs, it is useful to use diff as language to specify required changes.

Github and editors render like this:

Generate social previews

It would be great to generate a social preview card for each page, based on the title / description from the page.

I believe this could be done during nuxt generate.

Move releases to a serverMiddleware

Removing the marked dependency and avoiding using the GH Token on the front-end part (SPA fallback).

I think it would be nice also to show a page more a la Maintainers Changelog.

Refactor github config

• github should be a String or an Object with
  • repo (value is github is a string)
  • branch, default 'main'
  • apiUrl, default: 'https://api.github.com'
  • dir, default ''

Issues with blurry navbar

I don't know if it is intended by design or not but currently when jumping to a page using # anchors, the title goes behind blurry nav which is bad UX imo:

Some suggestions:

• Using different position for nav compoonent (still we will have issue for mobile/responsive design)
• Customize scroll behavior to jump with margin considering nav height

Support Nuxt Image

Fix layout shifts

Missing border on single layout

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Error type: undefined. Note: this is a nested preset so please contact the preset author if you are unable to fix it yourself.

Support a way to unprose

The initial idea I explored was be to add a .unprose class to the custom element.

After some research, it seems that it is not possible easily:

• https://twitter.com/adamwathan/status/1306643875994447874
• tailwindlabs/tailwindcss-typography#32 (comment)

We need another way to achieve this, I have been looking at how TailwindCSS website approach this issue, they use a Remark plugin to add the prose class to Markdown elements:

• https://github.com/tailwindlabs/tailwindcss.com/blob/master/remark/withProse.js

This will avoid having having to overwrites all style to unprose manually, example of what I want to achieve:

Docus Logo

CodeGroup active tab is wrong when use `active` on second codeblock

Only need one icon

The idea is to be a light as possible, a simple icon.svg (fallback to icon.png) should be required.

• Update pwa to handle .svg (nuxt-community/pwa-module#398)
• Remove the use icon-light.svgand icon-dark.svg
• Possibility to add icon-dark.svg

Error page

Work on a nicer error layout for error page.

Docus does not serve subdirectories

Directory structure:

- content
-  -  en
-  -  -  -  examples
-  -  -  -  -  -  index.md

With this structure /examples route return 404

Improve `AppPageBottom` component to fetch the `dir` from @nuxt/content

Instead of hard-coded content

Support pages/ in docus

Document version is broken

Using version does not work anymore @benjamincanac

Prose isuue with multiline components