A presentation at FEDucation with IBM by Ben Hong
VUEPRESS CREATING BEAUTIFUL DOCS YOU WILL WANT TO MAINTAIN Ben Hong @bencodezen Tuesday, April 9th, 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://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 documentation, beyond the simple README file of a repository, it’s quite difficult to get a proper documentation site setup. Many teams are relegated to heavy software like Confluence where documentation is separate from the codebase which often leads to outdated docs. Fortunately for us, the founder of Vue.js has created a tool that is optimized for creating beautiful technical documentation while empowering you to customize it as you see fit.
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.