search

nuxt-themes / docus

Write beautiful documentations with Nuxt and Markdown.
https://docus.dev
MIT License
1.54k stars 156 forks source link

Avoid using `pages/` directory for content #334

Closed pi0 closed 3 years ago

pi0 commented 3 years ago

pages/ directory, is reserved for Nuxt router purpose and following name => route map convention. Mixing with files that are neither part of the (bundled) source code or following the same structure, can be confusing both for users and module authors and introducing edge cases for deployments where should consider pages/ as a part of the built-only source while content/ needs to be deployed.

Tahul commented 3 years ago

Hey @pi0 😃, thanks for opening the issue!

Following our past discussions, I can understand the need for Nuxt and Docus not to conflict between each others.

To put it back in context, I guess that choice has been made because of our willingness to make things easy for the Docus end-user.

Being able to store .vue pages at the same place as your .md pages feels really great in terms of DX.

We need to clarify the distinction between how Nuxt Content worked, and how Docus works:

This is quite a different context and so this needs to be taken in account.

What makes the usage of pages/ so great for Docus is that it breaks the distinction between .vue files and .md files when it comes to the browsing experience, the pages/ folder reflects what will the website site map be:

pages/index.md => my-website.com/ pages/get-started.md => my-website.com/get-started pages/complex-page.vue => my-website/complex-page

Now that we have a little bit more context, I have few questions:

I don't think that is a feature that we want to drop from Docus, so we definitely need to find a solution that preserves that same level of end-user experience.

From my perspective right now the best approach would be to let the user define its own entry, allowing dirs/ and files.{md|vue}.

One of the "feature" of Docus will be that from only a docus.config.{js|ts}, you can make a website live out of any .md file or directory.

yarn add -D docus => npx docus dev => And I've got a nice looking website serving my README.md by default.

From that point, the user is free to make his documentation evolve at the pace of his repository, if he wants to use a directory for his documentation and take advantage of our default theme, he could then be specifying a dir/ instead of README.md as a Docus root, so from that he'll be able to start writing multiple pages of documentation.

We want Docus to be incrementally adoptable into your project, so it definitely has to support that kind of features which usage is shaped by its users.

I'm waiting for the feedback from @Atinux @farnabaz on that question 😄, I hope that we'll be able to find a proper solution!

farnabaz commented 3 years ago

I believe having different directory for markdown content makes sense for Nuxt Content module, since it is adding markdown feature for Nuxt project, and users can use these contents in any way they want.

But the goal of Docus is to create a layer above the Nuxt so users can create pages using either Vue or Docus specific markdown syntax therefor I think /pages directory is a right place for creating pages (either with Vue or Makrdown). Creating a separate place (/contents) to create markdown pages implies a separate meaning for /pages and /contents, this can look complicated for new users and misleading like @Tahul mentioned

However the concern about regression and edge-cases for modules is something we should consider. Do you think we can't prevent these edge-cases and regressions? @pi0

consider pages/ as a part of the built-only source while content/ needs to be deployed.

Aren't markdown files are build-only files? Why do we need to deploy these files to production?

pi0 commented 3 years ago

Hi @Tahul @farnabaz thanks for explaining :)

If we have to drop the usage of pages/ from Docus for another directory (content/ ?), what happens if a user wants to create a .vue page?

(nuxt) Users use pages/ to define a route based on filesystem structure. Docus is not adding one route per markdown but a mapping from a catch-all route to markdown paths.

If we allow the usage of .vue from another place than pages/, wouldn't it be misleading for users when switching from Docus to Nuxt projects?

We don't. components/ and pages/ are where vue source code is put. And content/ is where content. This is I would say much less confusing when learning about docus and nuxt than two conventions for naming in same dir.

Wouldn't the technical issues leading us to that discussion be avoidable from the Docus repository, let's say from a hook allowing us to update that pages/behavior?

Technically yes but it makes docus diverged from the nuxt ecosystem. You probably will need patches over time and docus flavored deployment instructions that are different than standard nuxt/nitro deployment.

Aren't markdown files are build-only files? Why do we need to deploy these files to production?

@farnabaz No they are generate-time (the step after nuxt build which is skipped via build cache) and soon with content v2 / nitro, they will be real runtime (incrementally generated on demand so we need them)

yarn add -D docus => npx docus dev => And I've got a nice looking website serving my README.md by default.

If this is the vision (which I think is pretty neat) probably can default customizable content dir to top-level and use src for customizations? :) At least for most of the documentation deployments in nuxt-community/nuxt should make sense since non need to create a .vue page but basically an alternative to vuepress/vitepress that has same possibility.

atinux commented 3 years ago

Thank you guys for all the comments and insights 🔥

If Docus is similar to VuePress and own the current directory, I believe defining a src/ directory to have all the user Nuxt code could be a nice solution without adding any compromise.

What do you think?

Only issues I can think of is for static/ dir and nuxt.config.js 🤔

Tahul commented 3 years ago

I like the idea but one question still remains besides that:

Are we going to preserve the fact that users can mix .md(v ?) and .vue files in the same directory, and get a filesystem based routing out of it?

Templates such as Vitesse by Antfu supports that, and I think it is a big loss for us to lose that too.

atinux commented 3 years ago

I don’t think so if the src/ directory contains the build files (everything with is webpacked).

Vitesse can’t be compared since it is bundle the Markdown files and generating a route for it.

The power of Nuxt Content and Docus is separating the Markdown from the build.

atinux commented 3 years ago

I also believe only a few projects will actually need pages/ AND src/pages/

atinux commented 3 years ago

Last but not least, it gives also the possibility for Docus to have its own directories that are not directly related to Nuxt

Tahul commented 3 years ago

Well, I'm fine with using src/ and a specific root for Docus, that is defined by the user.

That is also questioning how to use Docus as a package too, for now the structure we use ships a default Nuxt app config and uses nuxt-extend, to get the current user directory Nuxt config and project files.

I'm curious on how to implement that structure into our current project.

I don't know if we can do that with Nuxt 2 ?

Are these changes needed before migrating to Nuxt 3 ?

If removing the usage of pages/ is needed before releasing new packages documentation such as @nuxt/image, I think the best would be to rollback to content and only support .md files for now.

I tried to split our current structure so we have "pre-splitted" modules when we merge and update our structure with Nuxt 3, but don't really know if we can use Nuxt this way currently?

If you have any documentation I could read or any exemple of implementation from any other project I would be glad to read it!

Thanks for this discussion, it brings a lot of interesting question for Docus and will sure be helpful in defining next steps for this project! 😄

pi0 commented 3 years ago

content/ dir seems a nice option and easiest way to migrate existing content-docs-theme based websites and easier to try with multisource system 👍

I'm curious on how to implement that structure into our current project.

It should be the same system of extending. I've to add a new _apps/_layers property to nuxt-extend this way modules can scan each layer separately if that's what you are thinking to split.

Are these changes needed before migrating to Nuxt 3?

Yes. Since we are already doing docus migration on existing prod docs.

Templates such as Vitesse by Antfu supports that, and I think it is a big loss for us to lose that too.

As @Atinux mentioned, indeed it is a whole different strategy by docus/content for handling markdown/content separated from build (which btw Vitesse approach is also possible in nuxt for a long time defining pages with markdown (markdownit-module)

bdrtsky commented 3 years ago

Hm, what is exact reason of disabling .vue files support in content? Not to confuse the user? But isn't this an option, so user can decide use it or not. Also Docus content is different from Nuxt Content, where I totally agree having .vue files doesn't make any sense, since it's a basically a DB.

atinux commented 3 years ago

After discussing with @alexchopin, we are going to go back with content/ directory for managing pages with Docus, this way we keep full power of Nuxt without any tricks.

Most of the users will end up with such structure anyway:

content/
  index.md
docus.config.ts
package.json

The case of having both pages/ & content/ will be rare.

I am sorry to have asked to merge pages and content before, it was for DX but at the same time leading to poorer integration later on. Let's see how it gives with going back with content/ for Docus. I apologize for this situation.