search

obedm503 / bootmark

markdown + bootstrap as a jQuery plugin
https://obedm503.github.io/bootmark/
MIT License
21 stars 4 forks source link

RFC: new API #26

Open obedm503 opened 6 years ago

obedm503 commented 6 years ago

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

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 commented 6 years ago

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

oupala commented 6 years ago

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 commented 6 years ago

CSS framework

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

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 commented 6 years ago

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

obedm503 commented 6 years ago

: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 commented 6 years ago

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 commented 6 years ago

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

oupala commented 6 years ago

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:

Why is bootmark splitted into 3 different bundles?

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

obedm503 commented 6 years ago

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 commented 6 years ago

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

edthedev commented 5 years ago

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!