Code Monkeys

# VuePress Tutorial 4 - Directory Structure

By: J the Code Monkey
•Posted: Jan 22, 2022 •Updated: Jul 17, 2024

# 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 (Optional)
│   ├── releases
│   │   └── yarn-1.22.17.cjs
├── docs
│   └── README.md
├── node_modules
├── .gitattributes (Optional)
├── .gitignore
├── .yarnrc (Optional)
├── LICENSE
├── package.json
├── README.md
└── yarn.lock
  • .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.

Reminder to Update the .gitattributes and .gitignore Files

If you created your own repository and are using a locally set version of yarn, then be sure to update your .gitignore file and add a .gitattributes file as described in the Installing Yarn 1 post.

# 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 described 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 of our current directory structure and the package.json file, let's discuss the recommended directory structure.

Here's the recommended directory structure for a standard VuePress (opens new window) site:

.
├── docs
│   ├── .vuepress (Optional)
│   │    ├── components (Optional)
│   │    ├── public (Optional)
│   │    ├── styles (Optional)
│   │    │   ├── index.styl
│   │    │   └── palette.styl
│   │    ├── templates (Optional, Danger Zone)
│   │    │   ├── dev.html
│   │    │   └── ssr.html
│   │    ├── theme (Optional)
│   │    │   └── Layout.vue
│   │    ├── config.js (Optional)
│   │    └── enhanceApp.js (Optional)
│   │
│   ├── README.md
│   └── example-page
│       └── README.md
│
└── package.json

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 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).
  • docs/example-page/README.md: An example document which is used as another page for the site. Here, the route for the page is the directory name, i.e., /example-page/.
  • package.json: Describes metadata about your site (same file described in the current directory structure section).

Using the Recommended Directory Structure for Themes

If you plan on writing your own theme for your site or you plan on closely following along with these tutorials, then be sure to use the recommended directory structure for themes instead of the recommended directory structure for a standard VuePress (opens new window) site.

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

Here's the recommended directory structure if you plan on writing your own theme for your site. Since the Code Monkeys Blog is a child theme inherited from the default theme (opens new window), we'll be using the recommended directory structure for themes when developing the blog.

We'll be going over child themes and parent themes in more detail in future tutorials, but if you want to learn more now, you can read through the Theme Inheritance (opens new window) documentation.

If you're not using a theme when developing your site, you have the option of using the recommended directory structure for a standard VuePress (opens new window) site. There should only be minor differences when following along with these tutorials.

Only the Layout.vue file is mandatory when writing a theme, but we'll be using the other recommended directories as we continue to develop the blog.

.
├── docs
│   ├── .vuepress
│   │   ├── public
│   │   ├── theme
│   │   │   ├── components
│   │   │   ├── global-components
│   │   │   ├── layouts
│   │   │   │   └── Layout.vue (Mandatory)
│   │   │   ├── styles
│   │   │   │   ├── index.styl
│   │   │   │   └── palette.styl
│   │   │   ├── templates
│   │   │   │   ├── dev.html
│   │   │   │   └── ssr.html
│   │   │   ├── enhanceApp.js
│   │   │   └── index.js
│   │   └── config.js
│   │
│   ├── README.md
│   └── example-page
│       └── README.md
│
└── package.json

Capitalization

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

  • docs/.vuepress: Stores the global configuration, theme, static resources, etc.
  • docs/.vuepress/public: Static resource directory.
  • docs/.vuepress/theme: Stores the theme of the site.
  • theme/components: Stores the Vue components.
  • theme/global-components: The Vue components in this directory automatically get registered as global components.
  • theme/layouts: Stores the layout components used by the theme.
  • theme/layouts/Layout.vue: Mandatory layout component used by the theme.
  • theme/styles: Stores style related files.
  • theme/styles/index.styl: Used to add global styles that can override the default styles.
  • theme/styles/palette.styl: Used to define global styling variables and override the default styling variables.
  • theme/templates: Stores HTML template files.
  • theme/templates/dev.html: HTML template file for development environment.
  • theme/templates/ssr.html: HTML template file used in the build time.
  • theme/enhanceApp.js: Theme level enhancement.
  • theme/index.js: Entry file for theme configuration.
  • docs/.vuepress/config.js: Entry file for configuration, can also be yml or toml.
  • 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).
  • docs/example-page/README.md: An example document which is used as another page for the site. Here, the route for the page is the directory name, i.e., /example-page/.
  • package.json: Describes metadata about your site (same file described in the current directory structure section).

We'll be discussing themes in more detail as we continue to develop the blog. If you want to learn more now though or have any questions, then check out the Theme (opens new window) documentation.

# 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. Here are the relative paths and the default page routing paths for the directory structure described above:

Relative Path Page Routing
/README.md /
/example-page/README.md /example-page/

From the table we can see the relative path for the homepage is /README.md and the default page routing path for the homepage is /. We can also see the relative path for the example page is /example-page/README.md, and the default page routing path for the example page is /example-page/.

# Next Steps

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

Made by & for Code Monkeys 🐵