Optimize Playground Tutorial for maintenance and community contribution

[ikoevska]

Two separate community contributions have exposed a maintenance issue with the Playground Tutorial. Because the tutorial constantly references finished code, when you suggest a change to the code, you need to copy/paste it in several places (which is not an obvious action). We need to look into a way to optimize the code blocks of the tutorial to make it easier and more error-proof to contribute to the code.

[rigor789]

There is a way to set the code contents of a playground using a not-documented approach (needs a whitelist as well), maybe we could somehow auto-create the playground when code changes?

Another idea would be to have a file(s) with the actual code, and figure out a way to reference it in the docs by line numbers, in the markdown it could be something like

[code_reference from="app.js" lines="22-34"]

This would make syncing easier, but introduce the issue that if a line is added, every code reference needs to be updated.

I have a few more ideas, maybe have the source file in a format where we can "tag" blocks, for example

<block name="intro">
const Vue = require('nativescript-vue')

new Vue({
  // ...
</block>

<block name="template">
  template: `
    <!-- template here -->
  `
</block>

and then referenced in markdown with

[code_reference from="app.js" block="template"]

None of these seem ideal though, and introduce a different challenge...

[ikoevska]

Wow, how did I miss that?! Let's explore further.

[rigor789]

I think we need to move to VuePress sooner or later, and it has this exact feature built-in (although in beta) https://vuepress.vuejs.org/guide/markdown.html#import-code-snippets

[ikoevska]

How can I support you in moving to VuePress? We can maybe come up with a list of related tasks and can start tackling them?

[rigor789]

I think the biggest task to tackle would be to create the theme compatible with VuePress. Migrating content would be just a matter of shuffling files around a little and changing front matter where needed (at least in theory)...

I guess we could start a new branch with VuePress default theme, and start migrating content to it - and then I can start working on our theme. Some features we need might not be available in the default theme but we should be able to get most of it functional.

Does this sound good?

[ikoevska]

Sounds good. Let's do it. :)

[rigor789]

I've created a vuepress branch at https://github.com/nativescript-vue/nativescript-vue.org/tree/vuepress

I removed lots of files, just to slowly get the setup working (faster builds).

I started with the sidebar, and some basic configuration.

Since we'll have a custom theme, a lot of the configuration will be custom made - so I don't think there's a need to do much more with it right now.

A next step would be to re-think the structure of the files, things to get rid of, simplify etc.