Need Assistance with Docus Documentation: Understanding Headers, Asides, and Navigations
PrimalOutshoot opened this issue · comments
I've spent weeks trying to understand the limitations of what I can and can't do using the docus navigation - as someone who has very little experience with Nuxt 3 and Vite and Vue this is all new to me. Here are a few of the challenges I've run into:
Headers
header: {
logo: false, //components/Logo.vue
showLinkIcon: false,
exclude: [],
fluid: true
},
There are no examples that show me what I can exclude here - or how. The header appears to be the navigation, but adding page-1.md to /content/page-md does not automatically add it to the header - so what exactly gets excluded do here and how?
Different Asides for different Folder contents or Pages
I just figured out how to exclude - aside items.
aside: { //left menu
level: 0,
collapsed: true,
exclude: ['/folder-1', '/folder-2', '/folder-3', '/folder-4']
},
But then how do I add a secondary-aside menu (aside-1) that includes - the files I just excluded - and then how would I actually use aside-1 without having to create entire new page-layouts and manually editing each page in the folder with the aside to include that new aside.
aside-1: { //left menu
level: 0,
collapsed: true,
exclude: ['/folder-2', '/folder-3', '/folder-4', '/folder-5',]
},
Alternatively right now
/content - is automatically treated as part of the aside - how do I create
/content-2 - and have that automatically treated as part of aside-2, and simply linking to any page within the /content-2 gives you access to the aside-2 menu - in a way that is not overly complex.
Navigations
Navigations....
How do I actually add pages I want to the the navigation bar/header bar. Adding page1.md to the /content root folder just makes it accessible when I link to it - but it does not automatically add it to the Navigation where I can then exclude it.
Examples
An example of a website using docus that does what I am trying to do is "https://sidebase.io/"
There is a Navigation bar that has custom page elements Sidebase/Modules/Blog
When I click Sidebase - the left Aside has custom links unique to it.
When I click Modules - it utilizes an entirely separate Aside
While clicking Blog - takes me to a blog page - how would I even create a blog page within the docu theme?
Exploring the code of sidebase.io from it's github page, and downloading it directly did not give me any clear answers.
Customizing CSS with darkmode
I understand that Docus uses colorMode from nuxt. But I don't understand how when I create custom CSS elements, how to add my own dark version of the CSS. The docu seems to use @dark when it wants to show @dark css styles, but this does not work when I try it in my components or my :root css styling.
The only work around I have been able to find has been to build my site using single RGBA's that adjust the opacity of the RGBA colour dynamically based on the luminance of the background - or I use colours with alphas that look good on both light and background - because there is no clear or easy to understand way to override docus darkmode/lightmode options with my own. This work-around works fine for me - but if there is an easier way to do this both within the component and in the :root override I would love to know.
Icons
Docus uses "https://icones.js.org/" - which is a great library. The problem I am having is that some of their icons are one colour and some have colours - but I cannot override the icons with my own gradient styles. Using the docu theme - I doņ't know how to access the SVGs to make them gradient, the same way I could if I had a sass/icons with all my icons installed - just by virtue of the way components and node-modules work. If I were using the traditional sass structure I would have direct access to the .scss files and modify as needed that way - but this appears to be different. Knowing how I would do this specific to docus would be great.
TOC
I understand how to disable TOC on the right hand side, but is there any flexibility with where I can add it and how? How do add that same TOC within the markdown page inline - so that the TOC floats to the left or right of my content, instead of being separate from it - or sits at the top of the page - is that even possible to do without custom coding a new TOC vue component?
Have your problems been solved? That's what I want to know