A presentation at Vue Philly - August Edition by Ben Hong
VUEPRESS CREATING BEAUTIFUL DOCS YOU WILL WANT TO MAINTAIN Ben Hong @bencodezen Wednesday, August 21st, 2019
BEN HONG
BEN HONG
BEN HONG Senior Frontend Engineer @ Meltano in GitLab @bencodezen
VueDC https://www.vuedc.io BEN HONG Senior Frontend Engineer @ Meltano in GitLab @bencodezen Vue.js Events https://events.vuejs.org
BEFORE WE GET STARTED… SLIDES WILL BE AVAILABLE ONLINE https://www.twitter.com/bencodezen FOR THE SOCIAL MEDIA FOLKS @bencodezen - #VuePress
(╯°□°）╯︵ ┻━┻)
Yeah. I’m gonna need you to document that in Confluence…
THE PROBLEM WITH CONFLUENCE 1. Behind a paywall
THE PROBLEM WITH CONFLUENCE 1. Behind a paywall 2. Separate from your code
THE PROBLEM WITH CONFLUENCE 1. Behind a paywall 2. Separate from your code 3. Difficult to customize
THE PROBLEM WITH CONFLUENCE 1. Behind a paywall 2. Separate from your code 3. Difficult to customize
So tell me more about this VuePress thing…
VUEPRESS
“ VuePress is a static site generator with a Vue powered theming system that comes with a default theme optimized for technical documentation.
IT’S OPEN SOURCE SO IT’S 100% FREE
IT LIVES SIDE BY SIDE WITH YOUR CODE
OPTIMIZED FOR YOUR WRITING EXPERIENCE
COOL MARKDOWN EXTENSIONS: YAML FRONT MATTER README.md http://localhost:8080/ —title: Write Docs Like a Pro lang: en-US ——Writing docs can be hard, but with VuePress it’s so much more fun! Writing docs can be hard, but with VuePress it’s so much more fun!
COOL MARKDOWN EXTENSIONS: YAML FRONT MATTER README.md ——{ “title”: “Write Docs Like a Pro”, “lang”: “en-US” } ——Writing docs can be hard, but with VuePress it’s so much more fun! http://localhost:8080/ Writing docs can be hard, but with VuePress it’s so much more fun!
COOL MARKDOWN EXTENSIONS: EMOJIS README.md http://localhost:8080/ :fire: :fire: :fire: :fire: :fire: :fire: :fire: :fire: :fire: :fire: :fire: :fire: :fire: :fire: :fire: :fire: :cat: Everything is fine… 🔥🔥🔥🔥🔥🔥🔥🔥 :fire: :fire: :fire: :fire: :fire: :fire: :fire: :fire: 🔥🔥🔥🔥🔥🔥🔥🔥 :fire: :fire: :fire: :fire: :fire: :fire: :fire: :fire: 🐱 Everything is fine… 🔥🔥🔥🔥🔥🔥🔥🔥 🔥🔥🔥🔥🔥🔥🔥🔥
COOL MARKDOWN EXTENSIONS: SYNTAX HIGHLIGHTING README.md
js export default { data () { return { msg: 'Highlighted!' } } }
README.md
js export default { data () { return { msg: 'Highlighted!' } } }
http://localhost:8080/
README.md
js{4} export default { data () { return { msg: 'Highlighted!' } } }
http://localhost:8080/
COOL MARKDOWN EXTENSIONS: CUSTOM CONTAINERS README.md http://localhost:8080/ ::: tip This is a tip ::: ::: warning This is a warning ::: ::: danger This is a dangerous warning :::
README.md ::: tip This is a tip ::: ::: warning This is a warning ::: ::: danger This is a dangerous warning :::
http://localhost:8080/
COOL MARKDOWN EXTENSIONS: CUSTOM CONTAINERS README.md http://localhost:8080/ ::: tip This is a tip ::: ::: warning This is a warning ::: ::: danger This is a dangerous warning :::
README.md
::: tip Bringing it all together! We can write normal text and even include other extensions in this! js{5} const list = [1, 2, 3] list.map(item => { // This is so cool console.log(item ** 2) }) :rocket: :rocket: :rocket: :::
http://localhost:8080/
IT COMES WITH A DEFAULT THEME THAT IS…
VuePress Official Docs: https://vuepress.vuejs.org/
IT COMES WITH A DEFAULT THEME THAT IS 🔥 Responsive theme with essential navigation features built out Automatic Last Updated meta field Internationalization ready when you need it Easily customizable Built in searching / autocomplete Automatic link generation to repo
“ 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 MAGIC: INTERPOLATION README.md # VuePress in Toronto http://localhost:8080/ {{ “Happy Friday!”.toUpperCase() }} VuePress in Toronto :wave: :wave: :wave: :wave: :wave: :wave: HAPPY FRIDAY! So glad to be here at VueConf Toronto with over {{ 200 + 200 }} people! 👋👋👋👋👋👋 Things I need to try: 1. Tim Horton’s 1. Poutine 1. All the maple flavored things! :maple: So glad to be here at VueConf Toronto with with over 400 people! Things I need to try: 1. Tim Horton’s 2. Poutine 3. All the maple flavored things! 🍁
README.md
README.md —city: Toronto —# VuePress in {{ $page.frontmatter.city }} {{ “Happy Friday!”.toUpperCase() }} :wave: :wave: :wave: :wave: :wave: :wave: So glad to be here at VueConf {{ $page.frontmatter.city }} with over {{ 200 + 200 }} people! Things I need to try: 1. Tim Horton’s 1. Poutine 1. All the maple flavored things! :maple:
YOU CAN USE VUE COMPONENTS IN YOUR MARKDOWN
http://localhost:8080/
HOW DO I GET STARTED? VuePress Official Docs: https://v1.vuepress.vuejs.org/ Ben’s VuePress Starter Kit https://github.com/bencodezen/vuepress-starter-kit
DOCUMENT ALL THE THINGS
THANKS EVERYONE! @BENCODEZEN
When it comes to the survival and adoption of any software project, it often boils down to one thing: documentation. And though this seems like a simple task, countless projects are unable to create the docs that users need. 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 built a tool that makes documentation a joy for both maintainers and users: VuePress.
The following resources were mentioned during the presentation or are useful additional information.
Here’s what was said about this presentation on social media.
for free. You
can too.