tutorial draft

[connor11528]

Hello there,

I wrote a tutorial for getting started with Vuelog, included below. It seems that to start a new project the best course of action is to clone the repo and delete many of the contents? This post is meant to outline how to get started building a blog with Vue and Vuelog, feedback appreciated

---

Build a static blog with Vue.js and Vuelog

In this tutorial we are going to go through building a static blogging application with Vuelog. Vuelog is built out of Vue.js and uses the marked markdown parser and compiler under the hood. This means that we get the full reactivity power of Vue 2 and Vuex and the simplicity of writing our posts in markdown format. Vuelog was created in China and takes internationalization very seriously. If you have readers that speak different languages Vuelog is an especially good static blogging choice. Under the hood Vuelog uses vue-i18n to render different language content based on the user's preferences.

The application

A static blogging application means that all of our content is hosted on the client side. We do not need a server to handle incoming requests or a database like MySQL or MongoDB to store our content. Instead our application will be made up entirely of HTML, CSS and Javascript. This decreases our hosting costs, can increase performance and simplify our application.

This blog application will feature pages for our portfolio work, an about page and a blog. Additionally, we will have an archive of posts grouped by year and category as well as social links. The application will be hosted live using Github Pages. The source code for the application and a demo are featured below.

Demo: http://connorleech.info/vuelog-starter/

Source code: https://github.com/connor11528/vuelog-starter

Alternatives

There are many other solutions for static blogging out there. One to keep an eye on for the Vue.js community is called [Nuxt] (https://github.com/nuxt/nuxt.js). It is very powerful and includes many additional features. However, it is not stable and has not yet released the 1.0 release yet. Additionally, the added features can introduce uncessary complexity into our application.

Hexo.js, gatsby and jekyll are alternative static blogging engines that do not use Vue.js.

Get started building

To start building a new Vuelog project you must fork or clone the Vuelog repository, install dependencies and then run the development server using the steps below:

$ git clone https://github.com/myst729/Vuelog.git my-repo-name
$ cd my-repo-name && npm install 
$ npm run dev 

The application will run on localhost:8080.

Customize our blog

The starting point for a new Vuelog project comes with a lot of boilerplate code. In order to get our own blog up and running we'll have to delete and refactor.

Most of the configuration happens in userdata/database.js and the userdata folder also holds our markdown posts.

The two sections to pay attention to are navigation and pages. We will update these values to reflect our custom blog structure:

// The image displayed in site header right beside the brand.
logo: './static/employbl_logo.png',

...

navigation: [
    {
      label: {'en-US': 'Work' },
      type: 'page',
      path: '/page/work'
    },
    {
      label: {'en-US': 'About' },
      type: 'page',
      path: '/page/about'
    },
    {
      label: {'en-US': 'Blog' },
      type: 'category',
      path: '/blog'
    },
    {
      label: {'en-US': 'Archive' },
      type: 'archive',
      path: '/archive'
    },
    {
      label: {'en-US': 'Links' },
      type: 'dropdown',
      path: '', // (OPTIONAL) dropdown can be routable too if you set a valid route path
      children: [
        {
          label: {'en-US': 'LinkedIn' },
          type: 'outgoing', // A plain link can redirect to an in-site route or an out-going URL
          link: 'http://linkedin.com/in/connorleech'
        },
        {
          label: 'GitHub',
          type: 'outgoing',
          link: 'https://github.com/connor11528'
        },
        {
          label: 'Twitter',
          type: 'outgoing',
          link: 'https://stackoverflow.com/users/1032492'
        }
      ]
    }
  ],

  pages: [
    {
      title: {'en-US': 'Work'},
      slug: 'work', // corresponds to markdown file name
      exclude: true,      // (OPTIONAL) `true` to exclude the page from archive view
      titleless: false,   // (OPTIONAL) `true` to hide the title in page view
      commentless: true, // (OPTIONAL) `true` to disable comments for the page
      draft: false        // (OPTIONAL) `true` to make the page temporarily inaccessible
    },
    {
      title: {'en-US': 'About'},
      slug: 'about',
      exclude: true,
      titleless: false,   // (OPTIONAL) `true` to hide the title in page view
      commentless: true, // (OPTIONAL) `true` to disable comments for the page
    }
  ],

The value for slug in the pages array maps to the title of the markdown file we define in userdata/pages/. This configuration file serves as a source of truth for defining the structure of our blog application. We can also dynamically define our navigation menu and update the header image. Static assets are stored in the static/ directory.

Create an example post

Now that we have defined the pages and navigation we'd like in out application we can create a new post called userdata/posts/2017/sample.md:

title: This is a sample title
category: docs
date: 2017-09-22
------------------------------------
Welcome to the **sample** post written in *markdown*!

<!-- zh-CN:+ -->  
This will show if the language is set to Mandarin

<!-- zh-CN:- -->

Including the metadata in the post title itself is optional but can be helpful down the line.

We then add that post to our array of posts in userdata/database.js:

  posts: [
    /* 2017 */
    {
      title: {'en-US': 'This is a sample title'},
      slug: 'sample',
      category: 'docs',
      date: '2017-09-22'
    },
    ...

Deploy to Github Pages

Create a github repo for your project and set the base path in userdata/database.js to the name of your github repo:

base: '/name-of-github-repo/',

In order to deploy our application we first have to compile all of our vue files and assets. This command is defined in our package.json file and can be invoked by running: npm run build in the terminal. This generates our production application code into the docs folder.

Initialize a git repository for the project and commit all changes:

$ git init 
$ git add -A 
$ git commit -m 'initial commit'
$ git remote add orgin YOUR_GITHUB_HTTPS_OR_SSH_URL 
$ git push origin master 

Once we have built out our code we're going to reformat for production and push to the gh-pages branch.

$ git checkout -b gh-pages 
$ rm -rf static userdata
$ mv docs/* .

The above commands create a gh-pages branch, removes the static and userdata directories and then moves our production build folder from docs into their place. We are doing this because for the gh-pages branch we want the production build to be at root level.

If we make changes to our master branch and would like to redploy we can delete the gh-pages branch with the below command and deploy again according to the above process.

$ git push -d origin gh-pages
$ git branch -d gh-pages
$ git branch

Conclusion

Vuelog is a powerful tool for rendering a markdown blog with Vue.js. Under the hood it parses markdown and generates our application from a centralized configuration repository. The Vue.js source code is familiar and gives us power to create custom interactions for our users and provides lightning fast client side routing for our users.

As far as static blogging software goes Vuelog is not the most developed nor does it have the largest community. However it does utilize the power of Vue.js to render blog posts on the client. The codebase is small enough to be able to understand nearly in its entirety. If you are comfortable with Vue.js Vuelog is definitely worth exploring further for your blogging and static site needs.

[myst729]

• On alternatives such as Hexo, Jekyll:

  This has been discussed in other issues. So in brief, pros: no build process; cons: may not be friendly to SEO.

• On how to write:

  This is what the docs do. https://vuelog.js.org/

• On how to deploy:

  This is not what Vuelog was meant to care. You can deploy to wherever you like. GitHub is just one among the many options. https://pages.github.com/

• On how to hack:

  I published an NPM package back then (don't use it). It's almost dead because very few people would choose to hack rather than download the release package and start to write. However, hacking the source code is probably the only way to customize the default home page, as well as color scheme, etc. So really nice try.

[connor11528]

That is totally fine. It's cool that there is an npm package but I understand not needing to utilize it. It seems this is a project of a blog w/ Vue.js rather than a framework tool for building custom blogs. All good! Appreciate the feedback and I enjoy reading through the source code about how you built it 👏

[myst729]

The project was very simple in the beginning. Then it becomes bigger, as features are added one by one. The current state is not quite feasible regarding possibilities in the future. I might rewrite it when Vue 3.0 is released.