VuePress is a simple static site generator initially created to support the docs for large projects. It however it can do many more things as you are about to learn, personally I use it to generate . my website and blog Why VuePress: Makes your website blazing fast & SEO friendly. Development is super simple and an absolute joy. Very clean separation of your content from the rest of your site. Provides a full-fledged Vue instance no different from normal development. You are still able to create custom routes, use Vue plugins, anything that you would be able to normally. Flexible plugin API which, for example, I am using to automatically generate an RSS feed for my blog every time I update the content. Use Markdown with markdown-it and its extensive ecosystem. Being able to use Vue components inside your markdown. Who this guide is for You want to create a static website powered by Vue ❌ → ✅ → ⤵️ Why are you even here? Continue Your website is content-centric (e.g. not a web app) ❌ → ✅ → ⤵️ Static is going to be tougher for you in general but you might checkout Nuxt Continue Your content is, or is going to be, in markdown ❌ → ✅ → ⤵️ If you are already on any kind of JAMstack Nuxt might be a better option for now Continue You want to create something else than docs for your project ❌ → ✅ → ⤵️ Creating docs? Continue to the VuePress docs , they are excellent for this. Continue How this will work To very briefly describe how this will end up working: You’ll have a git repo which contains your website content (markdown files) and your VuePress assets (theme, config, images etc.) in a separate folder called . .vuepress Every time you’ll run the markdown files you have created will be converted into HTML files using the available VuePress layout files in your theme. Additionally defined routes will also be pre-rendered. npm run build A folder will be produced filled with static assets that can be served by any ordinary web server such as NGINX or Apache. /dist Setup Ok, let’s get started, first off we’ll do al the usual stuff: Create the project folder mkdir my-project && cd my-project Create a valid file with package.json npm init Initialize Git with git init If you don’t want to copy all of that and to demonstrate the use of Vue components inside markdown you can fill in your project name here, copy the command below and that’s that! Now let’s get to the VuePress specific stuff: First off, add the VuePress package itself with npm i -D vuepress WARNING In this guide we are using VuePress v1 so depending on when you are reading this you might have to install to get the proper version. vuepress@next You can also add VuePress globally with to be able to use commands such as in the terminal but we'll add these commands as NPM scripts anyway so this is up to you. npm install -g vuepress vuepress dev Next up we’ll add the following scripts to our file: package.json "scripts": { "dev": "vuepress dev", "build": "vuepress build"}, This enables us to interact with the project in a more general way without any setup or global package requirements with and . and others npm run dev npm run build Ok time to create the project files, we’ll start of by creating a directory in our project folder root and throwing an file in there. Our project structure should now look something like this: .vuepress config.js my-project|--.vuepress| |--config.js|--node_modules|--package.json The directory is going to be the backbone of this project containing all the files concerning your website besides the actual content itself, this will be placed in the root of the project folder. .vuepress Wait what is in that weird folder? Basically the directory will contain anything Vue related: .vuepress - If you want to use a custom theme it will be in there in the folder theme - If you want to use Vue components inside your markdown you’ll place them there in the folder components - If you want to add custom routes you can do so there using the file. enhanceApp.js - If you want to tweak your markdown settings they will be available in there in the file. config.js This creates a very clean separation of your Vue related files and everything outside it (your markdown content). For some more info about this folder and what it will contain . check this out The config.js file As might have guessed this file will contain much of the configuration and options concerning your website including the config for your theme. A minimal config file will look like this: module.exports = { title: 'My Site', description: 'Welcome to my site.'} But we’ll start off by extending it a bit straight away by specifying the folder where the compiled assets should end up: module.exports = { title: 'My Site', description: 'Welcome to my site.', dest: "dist"} Now your static assets will end up in the folder in your root. By default these will end up inside the folder which is a bit messy and less generic. /dist .vuepress/dist Creating our fist content Since this project is originally geared towards documentation creation its only logical that the source for the file will be the file in the root of your project. Create the file and put some simple markdown in there like: index.html README.md # Use a titleAnd some more content- A list- for example Now it’s time to reap the fruits of our labor, if you’ve done everything correctly you should now be able to execute and check out your first webpage! npm run dev If everything looks good you can generate your new webpage using . npm run build Where does my markdown content end up? The way VuePress routes your compiled markdown files is very straightforward, with the exemption of which gets turned into an file the rest of the content can be found at their respective position inside the project. For example: [README.md](http://readme.md) index.html → /about.md /about.html → /posts/vuepress-rocks.md /posts/vuepress-rocks.md → /posts/README.md /posts Using static assets I can see why the VuePress team did this but I do hope there will be an option to change the current location as is the case with the output directory for the build. Currently your static assets should be placed inside and they will be available at the root of your project. .vuepress/public That’s it! Well done! You probably got your first VuePress site up and running, you probably want to create a custom theme though. No problem, . read more about that here Originally published at willwillems.com .
