Markdown + Mermaid template

[josephinoo]

Description

• ETA TEMPLATE
• ...
• ...

Related issue(s)

[asyncapi-bot]

We require all PRs to follow Conventional Commits specification.
More details 👇🏼

 No release type found in pull request title "Markdown + Mermaid template". Add a prefix to indicate what kind of release this pull request corresponds to. For reference, see https://www.conventionalcommits.org/

Available types:
 - feat: A new feature
 - fix: A bug fix
 - docs: Documentation only changes
 - style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
 - refactor: A code change that neither fixes a bug nor adds a feature
 - perf: A code change that improves performance
 - test: Adding missing tests or correcting existing tests
 - build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
 - ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
 - chore: Other changes that don't modify src or test files
 - revert: Reverts a previous commit

[josephinoo]

Hi @nikhilkalburgi, I am considering rendering using the ETA template and, instead of directly generating the markdown (MD), display the content in HTML format first. This way, we will be able to establish a clear relationship between the HTML and the corresponding MD. Also, we could include a button at the end to allow users to export the content in MD or even PDF format. What do you think ?
https://www.markdownguide.org/basic-syntax/

[nikhilkalburgi]

Hi @josephinoo,
That's a great Idea. We can also discuss this on Slack in details.
In Short:

1. We need to install Template engine like EJS or ETA to render HTML on preview
2. We need a tool to convert HTML to MD like Eg. turndown for export
3. Design the prototype for the final UI with options for export etc... (I have built the initial wireframe, but more to be done )
4. Build the individual objects like servers, schema, operations, diagrams by creating template files(.ejs or .eta) for each in the newly added ./components folder.
5. Other issues like support for avro schema etc.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues

Measures
0 Security Hotspots
No data about Coverage
No data about Duplication

See analysis details on SonarCloud

[nikhilkalburgi]

Hi @ivangsa @josephinoo,

Below you will find the prototype that I have designed on Figma

28.02.2024_13.51.56_REC-ezgif.com-mute-video.mp4

I would appreciate your input on this to improve it further.

I also tried to set the template engine ETA but found that it is not very compatible with VS Code Env. So, I have used EJS instead and have developed the project structure with it. Soon I will raise a PR.

[ivangsa]

hi @nikhilkalburgi

I think the diagram in second 0:09 doesn`t make too much sense but it would require something similar for the payload of each message

I would create a separate one for each message, because maybe they are shared objects between messages and it's nice to to have everything mixed up..

I think EJS is good, it has more traction behind and ETA features are not that definitive for this usage..

[ivangsa]

hi @nikhilkalburgi @josephinoo

because the extension is webpacked you can not access EJS templates by path, you need to pack them as resources with webpack,

here an example as how I solved this in another extension:
https://github.com/ZenWave360/karate-ide/blob/master/webpack.config.js#L42

then you can load the contents like this:

const testTemplateFile = require('./templates/test.feature.ejs');
...
render(testTemplateFile, targetFile, model);
...
// this renders the results to a file, but you can use as an example to get the contents
function render(template, target: vscode.Uri, model): Promise<void> {
    return new Promise((resolve, reject) => {
        const options = {};
        try {
            ejs.renderFile(path.join(__dirname, template), model, options, async function (err, output) {
                await vscode.workspace.fs.writeFile(target, Buffer.from((err && err.message) || output));
                resolve();
            });
        } catch (error) {
            console.error(error.message);
            reject(error);
        }
    });
}

[nikhilkalburgi]

Hi @ivangsa,

I had implemented it like below:

In webpack.confi.js:

plugins: [
    new CopyPlugin({
      patterns: [
                . . .
        {
                  from: 'src/components',
                  to: 'components'
        } 
      ]

This will copy the .ejs files in ./components folder into ./dist/components

then:

const templatePath = path.join(context.extensionPath,'dist', 'components','Asyncapi.ejs');
await ejs.renderFile(templatePath , { ... });

But, now I am following your suggestion.

Initially, I will build the markdown for the objects and later integrate the mermaid diagrams

[ivangsa]

@nikhilkalburgi if it works in all cases, development and packaged, don't need to change it..

[nikhilkalburgi]

@nikhilkalburgi if it works in all cases, development and packaged, don't need to change it..

Okay!