Build a basic responsive website that includes iframes to examples, docs, and sandbox.

[ronyeh]

These URLs should work after this PR is completed:

http://vexflow.github.io/docs/
http://vexflow.github.io/examples/
http://vexflow.github.io/sandbox/

[ronyeh]

For an example how how to structure the repo to work with 11ty, see the sandbox repo:
https://github.com/vexflow/vexflow-sandbox

There's a GitHub workflow that builds the site:
https://github.com/vexflow/vexflow-sandbox/blob/main/.github/workflows/build.yml

[ronyeh]

To strip comments from HTML template files during the build process, we can use html-minifier in the .eleventy.js config file:

const htmlmin = require("html-minifier");

module.exports = function(eleventyConfig) {
  eleventyConfig.addTransform("htmlmin", function(content, outputPath) {
    if(outputPath && outputPath.endsWith(".html")) {
      return htmlmin.minify(content, {
        removeComments: true,
        collapseWhitespace: true,
      });
    }
    return content;
  });
};

https://www.npmjs.com/package/html-minifier

Options:

https://github.com/kangax/html-minifier?tab=readme-ov-file#options-quick-reference

[Prospero23]

Repo is using 11ty now. Just need to switch the served branch to be gh-pages :)

[Prospero23]

I don't believe I have access to settings to be able to change the branch that is being served, but obviously no rush on getting it changed.

[ronyeh]

It's serving from gh-pages now.

Thanks for submitting as PRs! It helps me quickly skim the changes. But if you find it to be a roadblock to quick development, then feel free to commit & push directly to the repo for now, since you're the only one on here. But later on, if we gain collaborators, then doing things with PRs makes it easier for folks to provide feedback, or for us to roll back to the last known good version if needed.

Question about the *.liquid extension:

11ty treats *.html files and *.md files as liquid templates by default. Should we use those extensions instead?

That's what I did in the vexflow-sandbox repo:
https://github.com/vexflow/vexflow-sandbox/tree/main/src

They're all liquid templates, but the file extension allows my text editor to more easily syntax color and pretty print the file.

Let me know if you think *.liquid is better. Whichever style we choose, we should be consistent across our repositories.

Other small bits of feedback:

• "Github Repo" on the top right. Should we rename to "Source Code"?

• We could optionally add this GitHub icon next to "Source Code". I took the SVG from the GitHub website. So it could look something like (maybe vertically centered):
  Source Code

• Should we go with docs/ or documentation/ in the path name? I guess docs/ is shorter but documentation/ is a real word. :-)

[Prospero23]

*.liquid

Should we use those extensions instead?

Totally. I completely missed that when reading the docs. First time really using 11ty so learning as I go. Always down for better syntax highlighting.

The go-to in vexflow-sandbox seems to be .html for html with {{ liquid stuff }} and whenever there is a front matter (I think thats the proper name?) its .md

Is that correct?

Naming Thoughts

Changing to "Source Code" with the GitHub icon makes sense to me.

I don't have a strong preference between docs and documentation other than docs feels slightly ~ chiller ~ lol

Other Formatting/Style Thoughts

I am not sold on how I have the accent-link class on the "Github Repo". I am going to keep messing around with it to make it look less weird to me.

The relationship between the homepage and sandbox feels pretty good. Obviously, the other two repos are not as seamless.

How do you think it would be best to share css styling between repos? I can start to separate out the css here so that the more general stuff can be centralized in a way that removes all the specific navigation styling etc.

I know that making a unified theme is probably a longer term goal, but I can start making steps towards making the process as painless as possible. Especially since our css is so basic, adding styles to other repos would be easy.

[ronyeh]

I didn't really have a convention for html vs md. I am also learning 11ty as I go, so I was trying out all the various template languages. You'll find a .njk layout file to wrap the markdown, and there are tons of other options. I decided webc files are not worth it for now. Let's just stick with html and md.

I tried md because you mentioned many of our v4 wiki tutorials could be ported over easily if we supported markdown.

Let's go with /docs/ for the path name. Our repo is vexflow-docs so we can be consistent. The menu item can say Documentation.

I'm thinking longer term, /docs/ will host versioned API docs along with getting started tutorials and other types of documentation.

As for css and static file sharing, maybe just have all of that under the root path vexflow.github.com/s/css/ and /s/js/ etc. We can make our sub sites reference those directly, or we can also introduce a build step in the future (as you mentioned earlier). The build step could pull from the sub repositories and build a master website.

Although now that I type it out, it does seem simpler to keep each repo separate and have the main parent site just include iframes! I know iframe is like 1990s technology, but if it works it works!!

[Prospero23]

if it works it works!!

+1 on that.

I think the largest gain that would come from a larger build step in the future would be some type of site-wide search using something like https://pagefind.app/. We could get something similar though just by adding localized searches in each of the child repos (even just docs and examples) in a similar vain of letting things that work, work.

Docs already have one, so it would be simple enough to just add something similar to examples and not have to really worry about it.

That css + file sharing idea works for me and i'll change that path name :)

[ronyeh]

Next week I'll look into vexflow-docs and how we can improve the organization and build process. Maybe we'll eventually have paths like:

• vexflow.com/api/5.0.0/
• vexflow.com/api/5.1.0/
• etc...
• vexflow.com/tutorial/
• vexflow.com/getting-started/

Once vexflow.github.io is ready, we'll have Mohit modify the http://vexflow.com/ CNAME to point to GitHub pages.

...

The GitHub Repo accent color is light blue at the moment.

If we look at the docs/ page, we see gray accents in light theme, and bluish-purple hues in the dark theme:
https://vexflow.github.io/documentation/

I don't think we customized anything.... it might just be the default typedoc light/dark themes.

See: https://typedoc.org/

Our VexFlow logo also has purple-blue hues.

I'd be fine if we just adopted the colors from the typedoc light/dark themes. If we want to make any tweaks, we can do it later on and pass along those tweaks to our typedoc css.