# VuePress Tutorial 4 - Directory Structure

By: Jay the Code Monkey
Posted: Jan 22, 2022 Updated: Aug 6, 2022

# Current Directory Structure

We're going to start with an overview of the current directory structure from the previous tutorial. Then we'll describe the recommended directory structure for a VuePress (opens new window) site.

The current directory structure of the project is based off of creating a repository for your project on GitHub (opens new window), cloning the repository, setting a local version of yarn for your project, and doing a manual installation of VuePress (opens new window). This means if you're not using a local version of yarn and/or did a quick start installation your current directory structure will be a little different.

Here's the current directory structure of the project:

  • .yarn/releases: Stores a local version of yarn for the project which ensures everyone working on the project is using the same version. If you didn't set a local version of yarn for your project, you won't have this directory.
  • .yarn/releases/yarn-1.22.17.cjs: Specific local version of yarn used in the code-monkeys-blog-tutorials (opens new window) and the code-monkeys-blog (opens new window) repositories. The file name will be different if you're using a different version.
  • docs/README.md: The first document for the site which will be used as the homepage.
  • node_modules: Contains all of the code for the installed packages.
  • .gitattributes: Used to prevent git from showing large diffs when you add or update local versions of yarn. If you didn't set a local version of yarn for your project, you won't have this file.
  • .gitignore: Ignores specified files and directories when making a commit to your repository.
  • .yarnrc: Instructs your global version of yarn to use the specified local version in the project. If you didn't set a local version of yarn for your project, you won't have this file.
  • LICENSE: Tells others how they can use your code.
  • package.json: Describes metadata about your site.
  • README.md: Used to describe your project in more detail and to document how to install and use your project.
  • yarn.lock: Keeps track of the exact versions of packages installed in the project. If you're using npm you'll have a package-lock.json file instead.

# Contents of the package.json file

Before moving on to the recommended directory structure, we're going to first go over the contents of the package.json file and add some simple updates.

The properties of your package.json file may be different depending on how you answered the questions when initializing your project and if you used the quick start installation method instead of the manual installation method. If you want to update any properties or values, you can edit your package.json file directly.

If you plan on publishing your project to the npm (opens new window) registry, then take a look at the npm package.json (opens new window) documentation to make sure you are following all of the specifications.

Here's what the contents of the package.json file looks like for the code-monkeys-blog-tutorials (opens new window):

The package.json file contains metadata about your project. This metadata includes information used to identify and describe your project and the packages you install which follow semantic versioning (semver) (opens new window).

Let's describe each property in a little more detail:

  • name is the name given to your project
  • version indicates the current version of your project
  • description is used to describe and provide more information about your project
  • main is a JavaScript file that starts the execution of your project
  • repository describes the location of the project repository containing the code
    • You can explicitly set the URL and a version control type in the package.json file by adding, e.g., "repository": { "type": "git", "url": "https://github.com/github-username/your-project" }
  • author describes the creator or owner of the project
    • You can explicitly set the author name, email, and website in the package.json file by adding, e.g., "author": { "name": "Your Name", "email": "youremail@example.com", "url": "https://your-website.com" }
  • license indicates the type of license being used by the project
  • scripts are command-line applications that are describe as an object where the property is the name of the script and the value is a command that gets run
  • devDependencies are dependencies you need during development only, i.e., not during production

Installing the Same VuePress Version

If you see a different version of VuePress (opens new window) and want to install the same version being used in the tutorials and blog, then you can run yarn upgrade vuepress@1.8.2.

Now, let's make some simple updates to the package.json file.

To start we're going to be adding a version control type to the repository property by updating it to be "repository": { "type": "git", "url": "https://github.com/github-username/your-project" }.

Next we're going to be adding an optional email and url to the author property by updating it to be "author": { "name": "Your Name", "email": "youremail@example.com", "url": "https://your-website.com" }.

If you prefer you can also shorten the author property to be one string by defining it like this "author": "Your Name <youremail@example.com> (https://your-website.com)".

The email could be a personal or work email, and the url could be a link to a personal website or the website related to your project.

Here's what the contents of the package.json file looks like for the code-monkeys-blog-tutorials (opens new window) after adding the updates:

Now that we have a good understanding or our current directory structure and the package.json file, let's discuss the recommended directory structure.

Here's the recommended directory structure for a VuePress (opens new window) site. Many of the directories and files are optional, and we'll be adding the directories and files we need as we go through the development of the site.

Be sure to check out the Directory Structure (opens new window) documentation if you have any questions.

Capitalization

When creating these directories and files be sure to follow the capitalization to prevent any potential issues.

  • docs/.vuepress: Stores the global configuration, components, static resources, etc.
  • docs/.vuepress/components: The Vue components (opens new window) in this directory automatically get registered as global components.
  • docs/.vuepress/public: Static resource directory.
  • docs/.vuepress/styles: Stores style related files.
  • docs/.vuepress/styles/index.styl: Used to add global styles that can override the default styles.
  • docs/.vuepress/styles/palette.styl: Used to define global styling variables and override the default styling variables.
  • docs/.vuepress/templates: Stores HTML template files.
  • docs/.vuepress/templates/dev.html: HTML template file for development environment.
  • docs/.vuepress/templates/ssr.html: HTML template file used in the build time.
  • docs/.vuepress/theme: Stores the local theme of the site.
  • docs/.vuepress/theme/Layout.vue: Layout component used by the theme
  • docs/.vuepress/config.js: Entry file for configuration, can also be yml or toml.
  • docs/.vuepress/enhanceApp.js: App level enhancement.
  • docs/README.md: The first document for the site which will be used as the homepage (same file described in the current directory structure section).
  • package.json: Describes metadata about your site (same file described in the current directory structure section).

# Default Page Routing

In the directory structure above we used the docs directory as the targetDir. If you want to learn more about how the targetDir is used, then take a look at the Command-line Interface (opens new window) documentation.

To see an example of the docs directory being used as the targetDir we can take a look at the scripts object we defined in the package.json file which is in the root directory of the project. Notice the targetDir gets set as the docs directory for the docs:dev and docs:build scripts:

All the relative paths are relative to the docs directory. So, for the directory structure above the relative path for the homepage is /README.md and the default page routing path for the homepage is /.

# Next Steps

In the next tutorial we'll discuss the basics of Configuration (opens new window).

Made by & for Code Monkeys 🐵