RFC: new API

[obedm503]

Background

I've been wanting to revitalize this project for a while now. There a few things that I'm not happy about. For example: the API and the fact that it uses jquery under the hood.

A few days ago @oupala brought a bunch of issues relating to CSP to mind. I decided to take the opportunity and rewrite the project with a much more focused mission in mind. And I've been looking for an excuse to use custom elements for a while now, more on that later.

Mission-ish

The purpose of this project is to give me an easy way to render markdown documentation. The target audience for such documentation are other developers. This means that I'm not worried about browser compatibility. I will only try to support the 4 main evergreen browsers. Meaning, IE is outside the scope of this project (but anyone can always add their own polyfills).

Background changes

• I'll probably use ionic-team/stencil to build the custom element/s. This should simplify the code hopefully making it easy enough to understand and contribute to.
• I'll move to using jgthms/bulma or franciscop/picnic instead of bootstrap. Bulma has a nice design and is just CSS. Also, there are a few bulma themes that should be able to replace bootswatch. Like Bulma, picnic is just CSS. But, unlike Bulma, it is semantic: meaning it requires very little classes to be added to the HTML. This simplifies the work bootstrap would have to do, making it faster. Picnic is also smaller than bulma which should reduce load time.
• Along the same lines, I be moving from google/code-prettify and showdownjs/prettify-extension to Bloggify/showdown-highlight because it abstracts highlight.js itself.

New API

In this issue, I would like to explore what a new API should look like while ignoring implementation details as much as possible. Because the previous API is so convoluted I would like to start from scratch while maintaining the good ideas.

Components

At the moment I'm thinking of creating 2 components: <bootmark-md> and <bootmark-app>. bootmark-md will handle converting one single markdown source into HTML and processing it according to whatever CSS library I decide to go with. bootmark-app will handle other niceties like a table of contents or a footer.

<bootmark-md>

<bootmark-md src="README.md"></bootmark-md>
<!-- or -->
<bootmark-md>
# Hello
- this 
- is 
- markdown
</bootmark-md>

custom showdown config?

const md = document.querySelector('bootmark-md');
Object.assign(md.showdown, {
  // override defaults
  simplifiedAutoLink: false, 
  literalMidWordUnderscores: false,
  // extensions will append to internal extensions
 extensions: ['any-other-showdown-extension'],
});

<bootmark-app>

<bootmark-app>
  <bootmark-md src="README.md"></bootmark-md>
  <hr> 
  <!-- will no longer need a "join" value since each instance of the component 
       handles a single source -->
  <bootmark-md src="CHANGELOG.md"></bootmark-md>
</bootmark-app>

Use with javascript

Because I'll no longer be using jquery under the hood or exposing anything as a jquery plugin, it will be impossible to do $('#id').bootmark({...}). Instead, the document.createElement API will be used.

const host = document.getElementById('id');
const md = document.createElement('bootmark-md');
md.src = 'README.md';
host.appendChild(md);

Theme

Theming will no longer be done automatically. Meaning bootmark will not auto-add links to stylesheets to the head. The how will depend on whether Bulma or picnic is used. If Bulma is used, all that is needed is to add either the original Bulma stylesheet or one of the themes. If picnic is used, I'll create a custom build that should allow theming through CSS variables.

Template?

No. This was an extremely unnecessary feature. Just no.

Syntax highlighting

Because bootmark will no longer auto add stylesheets, I will also be necessary to link a highlight.js theme. Here are all the themes and demos.

Also, bootmark will always add the showdown-highlight extension because it's used enough. Again, bootmark's purpose is displaying documentation, and documentation almost always has code samples.

[obedm503]

@oupala these changes should handle most concerns when it comes to strict CSP

[oupala]

I do applause the choice of stencil and bulma (although I didn't knew picnic, which might worth it either).

You can count on me for being a reactive tester! (with strict CSP enforced)

[obedm503]

CSS framework

After some thought, I'll be using bulma for the css framework for a few reasons:

• it already has several themes available, many of which are "ports" of the bootswatch themes
• anyone can create their own custom build with custom colors, round corners, etc
• the grid system is more intuitive than picnic's

Showdown config

In order for the component to rerender when showdown config changes, it is important to set the showdown property instead of just adding properties to the showdown object.

const md = document.querySelector('bootmark-md');
// setting the whole property
md.showdown =  {
  // override some defaults
  simplifiedAutoLink: false, 
  literalMidWordUnderscores: false,
  // extensions will append to internal extensions
 extensions: ['any-other-showdown-extension'],
};

[obedm503]

:tada: Bloggify/showdown-highlight#12 was merged :tada:

[obedm503]

:tada: just published version 0.9.0. because it's NOT stable, its available as @next

npm

npm install bootmark@next

cdn

<script src="https://unpkg.com/bootmark@next/dist/bootmark.js"></script>

for usage examples see html files in the docs/ directory in the development branch

@oupala let me know how it works with strict CSP

[oupala]

At this time, I did not tried with CSP, but I have an error related to stencil:

This Stencil app is disabled for this browser.

And I have tested with Firefox 60.2.2 (not that old) and 62.0.3. Same error with both of them.

[obedm503]

@oupala I accidentally published a development build. published 0.9.1. just tested on latest firefox, and it works

[oupala]

Ok, it works now, with the 0.9.1 version. The only problem I can see is that blockquotes ">" are not rendered).

For CSP validation, how could I test that with all resources local?

Here is what my browser is currently downloading:

• https://unpkg.com/bootmark@next/dist/bootmark.js (redirected to the following next resource)
• https://unpkg.com/[email protected]/dist/bootmark.js
• https://unpkg.com/bootmark@next/dist/bootmark/bootmark.hkemdqk8.js (redirection also)
• https://unpkg.com/[email protected]/dist/bootmark/bootmark.hkemdqk8.js
• https://unpkg.com/bootmark@next/dist/bootmark/hek4mfds.es5.entry.js (redirection also)
• https://unpkg.com/[email protected]/dist/bootmark/hek4mfds.es5.entry.js

Why is bootmark splitted into 3 different bundles?

I have no styling at this time, how can I add it by hand?

[obedm503]

It seems stencil doesn't automatically build a single bundle (see ionic-team/stencil#683). depending on how that progresses I may have to use rollup myself to bundle all those files.

As for styles, check html example files in docs/ in the development branch. You'll need to include either vanilla bulma or one of the themes

[oupala]

The styling is very light at the moment, but it works.

[edthedev]

This looks great. I really appreciate Bootmark and am looking forward to moving to the new version.

I also appreciate any efforts to keep it as light as possible, to keep collaboration and remixing simple.

Once the rewrite basics are done, I would be delighted to attempt to create a clean pull request to add link anchors to the navigation default navigation. It's the only thing I really miss using the current bootmark - the ability to link directly to a sub-section of a page.

Thanks again!