nejcm / docz-theme-extended

Extended default theme for docz with added components and redesigned UI.

🎀 docz-theme-extended

Extended default theme for docz with added components and redesigned UI.

Table of Contents

• Installation
• ⭐️ Features
• Docs & Examples
• Issues
  • 🐛 Bugs
  • 💡 Feature Requests
  • ❓ Questions
• Authors
• Contributors
• Support
• LICENSE

Installation

$ npm install --save @nejcm/docz-theme-extended

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: '@nejcm/docz-theme-extended',
    },
  ],
};

You can read more about using themes at Gatsby.

⭐️ Features

• Props table
• Sticky headers navigation sidebar
• Extended side menu that allows groups and sub-menus
• Footer navigation to previous and next document
• Optional fixed header
• Custom header logo
• Optional extended search that allows searching by tags
• Custom components like: Tabs, Tag, Hint, InlineCode ...

Docs & Examples

Docs & Examples

You can also check the demo project inside this repo for code examples and implementation details.

Issues

Looking to contribute? Look for the Good First Issue label.

🐛 Bugs

Please file an issue for bugs, missing documentation, or unexpected behavior.

See Bugs

💡 Feature Requests

Please file an issue to suggest new features. Vote on feature requests by adding a 👍. This helps maintainers prioritize what to work on.

See Feature Requests

❓ Questions

For questions related to using the library, please visit a support community instead of filing an issue on GitHub.

Authors

• Nejc Muršič ( GitHub, LinkedIn )

Contributing

The repository is a monorepo containing two projects:

• theme: the extended docz theme
• demo: the demo and docs for the extended theme

# Clone the project
git clone https://github.com/nejcm/docz-theme-extended.git my-project

# Install dependencies (yarn is required)
yarn install

# Run demo
yarn demo:dev

Check package.json file for more commands.

Contributors

Nejc Muršič 💻 📖 🚇 ⚠️

ATAlgaba 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Support

Reach out to us at one of the following places:

• 🌐 Website
• 📧 Email

LICENSE

MIT

docz-theme-extended's Issues

yarn install weight is extraordinary

Hello!

I want to first thank you for building this custom theme. I've been struggling with docz customization a lot lately, and this is a super helpful reference.

Slow install

When I try to use this theme, yarn install takes quite a while.

I needed to expand my node 10 heap size to 8GB just to get the command to execute. It required 20 minutes (!) on my Mac Pro with 96GB ram, 16 core Xeon.

Do you happen to know what is causing this exec time/weight?

Does it have something to do with yarn workspaces (which I'm not familiar with; I'm on [email protected])?

 

Extraneous dependencies

I looked at the dependencies in docz-theme-extended/theme.package.json and there looks like there's a number of superfluous dependencies:

• babel - devDependencies
• eslint - devDependencies
• prettier - devDependencies
• lint-staged - devDependencies
• husky - devDependency
• typescript - an entire copy of TypeScript hrm... perhaps it could be in peerDependencies ?

 

Thanks again!

Running yarn dev is very slow

When I run yarn dev, it compiles the project, its very resourceful, when its done, I go to localhost:3000 and it takes 10 minutes to show the docs, when I change something, that entire process needs to be repeated, using your theme extension looks very cool and it is useful, but the duration it takes just to get a result in dev mode is really intense, wait an hour to make 6 changes.

Any idea on what can be investigated on my environment that might be the reason for this delayed builds?

weird purple background color on main container.

clone docz-theme-extended demo folder, and change "@nejcm/docz-theme-extended": "*" to "@nejcm/docz-theme-extended": "^2.0.14" so it uses the npm package instead of the local package. and run yarn dev and you'll notice a purple background.

Feature Request - Props GUI

Something that is constantly brought up to me at my company is that they would really like a Props GUI to easily change the props in real time. Similar to how Storybook has knobs, each props would have a "knob" corresponding to their prop type. For example, a bool might be a checkbox, a string might be a text input, a oneOf might be a dropdown/select, a node might be an input for jsx, etc. All of these would be in a Component similar to the Props Table.

Thoughts? Is this doable? It would be extremely helpful to have this. Thank you in advance.

Console warning for initialColorMode

Running docz locally, there is always this warning in the console: The 'initialColorMode' value should be a unique name and cannot reference a key in 'theme.colors.modes'. It logs again on every page. I think the issue might be this line.

Not urgent, just gets in the way of real console errors.

Logo urls is wrong on production build

Hello i have an error with logo urls when i try to compile on production build
the problems is there https://github.com/nejcm/docz-theme-extended/blob/master/theme/src/gatsby-theme-docz/helpers/index.js#L14 the getPublicUrl its returned urls with 3 slashes

`/${(base || '').replace(/^\/|\/$/g, '')}/${src}` // here we added 2 slash + one from config

HTML

Demo

export default {
  lang: "en",
  title: "", // removed title because we use logo.svg
  description: "UI Components",
  host: "0.0.0.0",
  port: 9000,
  src: "./src",
  public: "./docs",
  typescript: true,
  files: "**/*.mdx",
  ignore: ["./*.md"],
  menu: [
    "Getting Started",
    "Actions",
    "Behavior",
    "Feedback indicators",
    "Forms",
    "Images and icons",
    "Lists and tables",
    "Navigation",
    "Overlays",
    "Structure",
    "Titles and text",
  ],
  themeConfig: {
    search: true,
    logo: {
      src: {
        light: "/docs/logo.svg",
        dark: "/docs/dark-logo.svg",
      },
      width: 125,
    },
    mainContainer: {
      fullscreen: false,
      align: "center",
    },
    header: {
      icons: "minimal",
      fixed: true,
    },
    footer: {
      navigation: true,
    },
    menu: {
      search: false,
      headings: {
        rightSide: true,
        scrollspy: true,
        depth: 3,
      },
    },
  },
};

subMenuGroups.some is not a function

When trying to use the menu search bar in the top left, I get the error: Uncaught TypeError: subMenuGroups.some is not a function. I'm guessing it was just an oversight when the submenu feature was added?

Node 14.15.4
React 16.13 && React 17
Babel 7
Docz 2.3.1
@nejcm/docz-theme-extended 2.0.10

Feature Request: Sub Menus

Hi! I think it's really cool what you've done here and will be using your theme extension! One thing I could really use is the ability to have sub menus in the main left menu. For example, I have several Form components with their own mdx page and I'd like to have them all in a menu under "Forms". So the folder structure would look like Components/Forms/Checkbox.

Bug: Bottom nav with sub menus

Using the new submenu feature, the 2 bottom navigation components show the previous/next components alphabetically instead of the previous/next components in the order of the menu+submenus.
For example, if my component is Radio under the submenu Forms, the previous component should be my NativeSelect component in the same Forms submenu and the next should be my Textarea component in the same Forms submenu. But instead, components with the previous/next alphabetical order are shown. Hopefully the screenshot clears up any confusion.

Bug: sub menus indexing

The new sub menu feature works as expected for my Accordion submenu. However, my other two sub menus Forms and Pagination appear at the very bottom of the menu instead of alphabetically. I've implemented them the same way so I don't see why they should appear at the bottom of the menu.

Accordion.mdx

---
menu: Components
name: Accordion
route: /Components/Accordion/Accordion
submenu: Accordion
---

Checkbox.mdx

---
menu: Components
name: Checkbox
route: /Components/Forms/Checkbox
submenu: Forms
---

Let me know if you need any other info and if the screenshots don't show up.