The "quick start" application skeleton does not comply with the recommended Directory Structure

[adriatic]

• I confirm that this is an issue rather than a question.

Bug report

Steps to reproduce

The Quick Start method to create the basic app skeleton results with the following structure

Note the src folder (red marker 3)! - this folder is not present in the Recommended structure

What is expected?

Most likely the Quick Start method creates the incorrect skeleton - the src folder seems redundant.

What is actually happening?

Other relevant information

• Output of npx vuepress info in my VuePress project:

npx vuepress info

Environment Info:

  System:
    OS: Windows 10 10.0.19041
    CPU: (8) x64 Intel(R) Core(TM) i7-7700 CPU @ 3.60GHz
  Binaries:
    Node: 12.19.0 - C:\Program Files\nodejs\node.EXE
    Yarn: 1.22.5 - C:\Program Files (x86)\Yarn\bin\yarn.CMD
    npm: 6.14.7 - C:\Program Files\nodejs\npm.CMD
  Browsers:
    Chrome: 87.0.4280.66
    Edge: Spartan (44.19041.423.0), Chromium (87.0.664.47)
  npmPackages:
    @vuepress/core:  1.7.1
    @vuepress/theme-default:  1.7.1
    vuepress: ^1.5.3 => 1.7.1
  npmGlobalPackages:
    vuepress: Not Found

[arafalov]

Also, the scripts are missing "docs:" prefixes which documentation say will be expected to be there.

[adriatic]

@arafalov upon looking a bit deeper, please realize that the two methods (quick start and manual installation) create different application skeletons. The scripts section of the package.json:

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

"fits" only the "manual installation" case. If you used the application skeleton generated by yarn create vuepress-site [optionalDirectoryName] (the quick method), then the scripts section is

"scripts": {
    "dev": "vuepress dev src",
    "build": "vuepress build src"
  },

which addresses the fact that where the folder hierarchy is docs->src->.vuepress.

[arafalov]

And this difference is part of the problem, right?

Because I (a beginner with Vue and VuePress) had read quick start and manual setup as alternative paths to the same goal. This is strengthened by the fact that quickstart does not actually include any run command and the only run command shown is npm run docs:dev. This uniformity is also indicated by text "the rest of the documentation will assume those scripts being added".

So, if we accept that Quickstart divergence from manual setup on such basic level is a feature and not a bug, this means that "The fastest way to get your VuePress project setup" is actually "The fastest way to not being able to use the rest of the documentation or even have an example of a working command".

I doubt that this was the intention.

[adriatic]

I believe that the following text describes the authors' intent:

1. The Quick Start is the description of "official generator", it is based on the most recent Scaffolding a VuePress project, a recent replacement for the deprecated create-vuepress document and code.

2. The Manual installation document is provided for people that want to add VuePress to an existing project - so it is minimally opinionated and a lot less complete than the Quick Start. The scripts JSON document that is a part of the Manual installation section CANNOT be used with the Quick Start (Scaffolding a VuePress project) generator.

I created and deployed the complete application at Netlify, accessible as https://eager-darwin-7c6186.netlify.app/. See Deploying VuePress site to Netlify document describing the creation process.

[arafalov]

Perhaps. All I can say is the confusion I experience as a first-time user. The way it is presented, it make it seems that both quickstart and manual parts are going to the same conclusion but at a different speed. The reality is that - for historical or other reasons - they are actually going in different directions. So, a clarifying sentence or two on that page would probably help onboard new people easier.

Specifically:

• I would add run command with correct name right under the the Quick Start and
• Add clarifying text for manual setup as you suggested
• Resolve/clarify/fix the part about "the rest of documentation will" as that cannot apply to both manual and Quickstart approaches simultaneously.

[adriatic]

I wrote the above comments for a person like myself who had to spend more time than I care to admit in order to find the correct way to generate the complete skeleton, without having to wait for the owners of the VuePress project to address the issues we both find.

My interest is to create a real blogging and documentation site using VuePress - not trying to suggest to the project owners how to re-organize VuePress documentation

[arafalov]

I think those "real-status" guides are very useful. Thank you for taking time to document the steps.

And, hopefully, they will also help to clarify the discrepancies for those who can resolve them in main documentation too.