Open adriatic opened 3 years ago
Also, the scripts are missing "docs:" prefixes which documentation say will be expected to be there.
@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
.
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.
I believe that the following text describes the authors' intent:
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.
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.
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 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
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.
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
npx vuepress info
in my VuePress project: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