A presentation at DevFestDC in in Arlington County, Arlington, VA, USA by Ben Hong
VUEPRESS DOCUMENTATION MADE EASY By Ben Hong www.bencodezen.com DEVFEST DC 2018
BEFORE WE GET STARTED... YOU CAN FIND THE SLIDES HERE: https://www.twitter.com/bencodezen AND FOR SOCIAL MEDIA POSTS: #vuepress
BEN HONG Senior UI Developer @ POLITICO @bencodezen
VUEDC https://www.vuedc.io BEN HONG Senior UI Developer @ POLITICO @bencodezen
VUEDC https://www.vuedc.io BEN HONG Senior UI Developer @ POLITICO @bencodezen VUEMEETUPS https://www.vuemeetups.org
“ Documentation can be difficult, but it is the key to any project's long term success.
README.MD
CONFLUENCE
CONFLUENCE
BUILD YOUR OWN
BUILD YOUR OWN What tech stack do you use?
BUILD YOUR OWN What tech stack do you use? What does the design look like?
BUILD YOUR OWN What tech stack do you use? What does the design look like? What features should it have?
BUILD YOUR OWN What tech stack do you use? What does the design look like? What features should it have? Is it easy to maintain?
BUILD YOUR OWN What tech stack do you use? What does the design look like? What features should it have? Is it easy to maintain? Who is going to pay for this?
LIVING & GOOD DOCUMENTATION IS HARD
ENTER VUEPRESS
“ VuePress is a static site generator with a Vue-powered theming system that comes with a default theme optimized for technical documentation.
WHAT MAKES VUEPRESS GREAT?
WHAT MAKES VUEPRESS GREAT? Provides an incredible default theme that allows you to focus on what's important: writing documentation
DEFAULT THEME FEATURES
DEFAULT THEME FEATURES 1. Homepage
DEFAULT THEME FEATURES 1. Homepage 2. Navbar
DEFAULT THEME FEATURES 1. Homepage 2. Navbar 3. Sidebar
DEFAULT THEME FEATURES 1. Homepage 2. Navbar 3. Sidebar 4. Built-in Search
DEFAULT THEME FEATURES 1. Homepage 2. Navbar 3. Sidebar 4. Built-in Search 5. Git Repo
DEFAULT THEME FEATURES 1. Homepage 2. Navbar 3. Sidebar 4. Built-in Search 5. Git Repo 6. Last Updated & Edit links
WHAT MAKES VUEPRESS GREAT? Provides an incredible default theme that allows you to focus on what's important: writing documentation
WHAT MAKES VUEPRESS GREAT? Provides an incredible default theme that allows you to focus on what's important: writing documentation It leverages technology and languages that developers are already comfortable with
THINGS YOU NEED TO KNOW
THINGS YOU NEED TO KNOW 1) npm install / npm run dev
THINGS YOU NEED TO KNOW 1) npm install / npm run dev 2) Markdown syntax
THINGS YOU NEED TO KNOW 1) npm install / npm run dev 2) Markdown syntax 3) Git
THINGS YOU NEED TO KNOW 1) npm install / npm run dev 2) Markdown syntax 3) Git 4) . . . That's it
WHAT MAKES VUEPRESS GREAT? Provides an incredible default theme that allows you to focus on what's important: writing documentation It leverages technology and languages that developers are already comfortable with
WHAT MAKES VUEPRESS GREAT? Provides an incredible default theme that allows you to focus on what's important: writing documentation It leverages technology and languages that developers are already comfortable with Contains built-in markdown extensions that are optimized for technical documentation
COOL MARKDOWN EXTENSIONS
COOL MARKDOWN EXTENSIONS 1. Emojis
COOL MARKDOWN EXTENSIONS 1. Emojis 2. Front Matter
COOL MARKDOWN EXTENSIONS 1. Emojis 2. Front Matter 3. GitHub-Style Tables
COOL MARKDOWN EXTENSIONS 1. Emojis 2. Front Matter 3. GitHub-Style Tables 4. Code Syntax Highlighting
COOL MARKDOWN EXTENSIONS 1. Emojis 2. Front Matter 3. GitHub-Style Tables 4. Code Syntax Highlighting 5. Line Highlighting in Code Blocks
COOL MARKDOWN EXTENSIONS 1. Emojis 2. Front Matter 3. GitHub-Style Tables 4. Code Syntax Highlighting 5. Line Highlighting in Code Blocks 6. Custom Containers
WHAT MAKES VUEPRESS GREAT? Provides an incredible default theme that allows you to focus on what's important: writing documentation It leverages technology and languages that developers are already comfortable with Contains built-in markdown extensions that are optimized for technical documentation
WHAT MAKES VUEPRESS GREAT? Provides an incredible default theme that allows you to focus on what's important: writing documentation It leverages technology and languages that developers are already comfortable with Contains built-in markdown extensions that are optimized for technical documentation Every page generated by VuePress has its own prerendered static HTML, providing great loading performance and is SEO-friendly
“ VuePress is a static site generator with a Vue-powered theming system that comes with a default theme optimized for technical documentation.
“ VuePress is a static site generator with a Vue-powered theming system that comes with a default theme optimized for technical documentation.
VUE.JS TLDR;
“ Vue is a progressive framework for building user interfaces. Unlike other monolithic frameworks, Vue is designed from the ground up to be incrementally adoptable.
https://stateofjs.com/2017/front-end/results/
THREE VUE.JS FEATURES
DECLARATIVE RENDERING <div id="app"> <h1>Hello {{ conference }}</h1> </div> <script> var app = new Vue({ el: '#app', data() { return { conference: 'DevFestDC!' } } }) </script>
DECLARATIVE RENDERING <div id="app"> <h1>Hello {{ conference }}</h1> </div> <script> var app = new Vue({ el: '#app', data() { return { conference: 'DevFestDC!' } } }) </script> Hello DevFestDC!
DIRECTIVES <div id="app"> <h1>Front-End Trifecta</h1> <ul> <li v-for="language in languages"> {{ language }} </li> </ul> </div> <script> var app = new Vue({ el: '#app', data() { return { languages: [ 'HTML', 'CSS', 'JavaScript' ] } } }) </script>
DIRECTIVES <div id="app"> <h1>Front-End Trifecta</h1> <ul> <li v-for="language in languages"> {{ language }} </li> </ul> </div> <script> var app = new Vue({ el: '#app', data() { return { languages: [ 'HTML', 'CSS', 'JavaScript' ] } } }) </script> Front-End Trifecta HTML CSS JavaScript
SINGLE FILE COMPONENTS <template> <div> <h2 class="title">Single File Components</h2> <p>They are {{ adjective }}!</p> </div> </template> <script> export default { name: 'SimpleComponent', data() { return { adjective: 'game changing' } } } </script> <style> .title { font-color: #BADA55; } </style>
SINGLE FILE COMPONENTS <template> <div> <h1>Single File Components In Action!</h1> <SimpleComponent /> <p>And we have some text here</p> <SimpleComponent /> </div> </template> <script> import SimpleComponent from './components/SimpleComponent' export default { name: 'App', components: { SimpleComponent } } </script>
“ Vue is the most compassionate framework in the market right now because it allows you to choose what's best for you.
BACK TO VUEPRESS
“ VuePress is a static site generator with a Vue-powered theming system that comes with a default theme optimized for technical documentation.
USE VUE IN MARKDOWN
USE VUE IN MARKDOWN 1. Interpolation
USE VUE IN MARKDOWN 1. Interpolation 2. Access Site and Page Data
USE VUE IN MARKDOWN 1. Interpolation 2. Access Site and Page Data 3. Directives
USE VUE IN MARKDOWN 1. Interpolation 2. Access Site and Page Data 3. Directives 4. Single File Components
HOW DO I GET STARTED? STARTED? https://vuepress.vuejs.org/ https://github.com/bencodezen /vuepress-starter-kit
Q&A
THANKS! @bencodezen
For those who have been lucky enough to work with Vue.js documentation, you know that it’s one of the best out there in the ecosystem. And true to the ethos of the Vue.js ecosystem, Evan You has just come out with another tool that makes documentation a piece of cake. In this talk, we’ll be going over what VuePress is along with why you should have it in your arsenal of tools!
The following resources were mentioned during the presentation or are useful additional information.
The official VuePress docs that will be very handy as you learn how to configure your VuePress site!
A tutorial that can help you get up and running pretty quickly. Some of the information in the advanced sections are a little out of date, but that can be easily reconciled by the official docs.
And in case you're wondering, yes I plan to write my own for everyone. More on that soon!
for free. You
can too.