Skip to content

Commit

Permalink
feat(#2039): Add cli flag to omit file header comment on stdout (#2312)
Browse files Browse the repository at this point in the history 
* feat: Add cli flag to omit file header comment on stdout

* docs: Add command line flag for omitting file header comment to docs, Cleanup markdown tables

* docs: Reformat table headers for cli flags

Overlooked on the first try ...
  • Loading branch information
@timo-reymann
timo-reymann committed Jun 29, 2021
1 parent 4f83e2c commit 9ecacf6
Show file tree
Hide file tree
Showing 3 changed files with 52 additions and 38 deletions.
73 changes: 38 additions & 35 deletions doc/install.md
View file
@@ -1,14 +1,16 @@
# Installation

You can install MJML with NPM to use it with NodeJS or the Command Line Interface. If you're not sure what those are, head over to <a href="#usage">Usage</a> for other ways to use MJML.
You can install MJML with NPM to use it with NodeJS or the Command Line Interface. If you're not sure what those are,
head over to <a href="#usage">Usage</a> for other ways to use MJML.

```bash
npm install mjml
```

# Development

To work on MJML, make changes and create merge requests, download and install [yarn](https://yarnpkg.com/lang/en/docs/install/) for easy development.
To work on MJML, make changes and create merge requests, download and
install [yarn](https://yarnpkg.com/lang/en/docs/install/) for easy development.

```bash
git clone https://github.com/mjmlio/mjml.git && cd mjml
Expand All @@ -31,11 +33,12 @@ Don't want to install anything? Use the free online editor!

## Applications and plugins

MJML comes with an ecosystem of tools and plugins, check out:
- The [MJML App](https://mjmlio.github.io/mjml-app/) (MJML is included)
- [Visual Studio Code plugin](https://github.com/mjmlio/vscode-mjml) (MJML is included)
- [Atom plugin](https://atom.io/users/mjmlio) (MJML needs to be installed separately)
- [Sublime Text plugin](https://packagecontrol.io/packages/MJML-syntax) (MJML needs to be installed separately)
MJML comes with an ecosystem of tools and plugins, check out:

- The [MJML App](https://mjmlio.github.io/mjml-app/) (MJML is included)
- [Visual Studio Code plugin](https://github.com/mjmlio/vscode-mjml) (MJML is included)
- [Atom plugin](https://atom.io/users/mjmlio) (MJML needs to be installed separately)
- [Sublime Text plugin](https://packagecontrol.io/packages/MJML-syntax) (MJML needs to be installed separately)

For more information, check the [Tooling](#tooling) section.
For more tools, check the [Community](https://mjml.io/community) page.
Expand All @@ -50,20 +53,20 @@ mjml input.mjml -o output.html

You can pass optional `arguments` to the CLI and combine them.

argument | description | default value
---------|--------|--------------
`mjml -m [input]` | Migrates a v3 MJML file to the v4 syntax | NA
`mjml [input] -o [output]` | Writes the output to [output] | NA
`mjml [input] -s` | Writes the output to `stdout` | NA
`mjml -w [input]` | Watches the changes made to `[input]` (file or folder) | NA
`mjml [input] --config.beautify` | Beautifies the output (`true` or `false`) | true
`mjml [input] --config.minify` | Minifies the output (`true` or `false`) | false
`mjml [input] --config.juicePreserveTags` | Preserve some tags when inlining css, see [mjml-cli documentation](https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md) for more info | NA
`mjml [input] --config.minifyOptions` | Options for html minifier, see [mjml-cli documentation](https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md) for more info | NA
`mjml [input] --config.mjmlConfigPath [mjmlconfigPath]` | Uses the `.mjmlconfig` file in the specified path or directory to include custom components | *The `.mjmlconfig` file in the current working directory, if any*
`mjml [input] --config.useMjmlConfigOptions` | Allows to use the `config` attribute from `.mjmlconfig` file | false
`mjml [input] --config.validationLevel` | [Validation level](https://github.com/mjmlio/mjml/tree/master/packages/mjml-validator#validating-mjml): 'strict', 'soft' or 'skip' | 'soft'

argument | description | default value
------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -----------------------------------------------------------------------------------
`mjml -m [input]` | Migrates a v3 MJML file to the v4 syntax | NA
`mjml [input] -o [output]` | Writes the output to [output] | NA
`mjml [input] -s` | Writes the output to `stdout` | NA
`mjml [input] -s --noStdoutFileComment` | Writes the output to `stdout` without an comment containing the source file in the first line | the outputs first line contains the file in the format `<!-- FILE: {filename} -->`
`mjml -w [input]` | Watches the changes made to `[input]` (file or folder) | NA
`mjml [input] --config.beautify` | Beautifies the output (`true` or `false`) | true
`mjml [input] --config.minify` | Minifies the output (`true` or `false`) | false
`mjml [input] --config.juicePreserveTags` | Preserve some tags when inlining css, see [mjml-cli documentation](https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md) for more info | NA
`mjml [input] --config.minifyOptions` | Options for html minifier, see [mjml-cli documentation](https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md) for more info | NA
`mjml [input] --config.mjmlConfigPath [mjmlconfigPath]` | Uses the `.mjmlconfig` file in the specified path or directory to include custom components | *The `.mjmlconfig` file in the current working directory, if any*
`mjml [input] --config.useMjmlConfigOptions` | Allows to use the `config` attribute from `.mjmlconfig` file | false
`mjml [input] --config.validationLevel` | [Validation level](https://github.com/mjmlio/mjml/tree/master/packages/mjml-validator#validating-mjml): 'strict', 'soft' or 'skip' | 'soft'

## Inside Node.js

Expand All @@ -87,7 +90,6 @@ const htmlOutput = mjml2html(`
</mjml>
`, options)


/*
Print the responsive HTML generated and MJML errors if any
*/
Expand All @@ -96,19 +98,20 @@ console.log(htmlOutput)

You can pass optional `options` as an object to the `mjml2html` function:

option | unit | description | default value
-------------|--------|--------------|---------------
fonts | object | Default fonts imported in the HTML rendered by HTML | See in [index.js](https://github.com/mjmlio/mjml/blob/master/packages/mjml-core/src/index.js#L36-L44)
keepComments | boolean | Option to keep comments in the HTML output | true
beautify | boolean | Option to beautify the HTML output | false
minify | boolean | Option to minify the HTML output | false
validationLevel | string | Available values for the [validator](https://github.com/mjmlio/mjml/tree/master/packages/mjml-validator#validating-mjml): 'strict', 'soft', 'skip' | 'soft'
filePath | string | Full path of the specified file to use when resolving paths from [`mj-include` components](#mj-include) | '.'
mjmlConfigPath | string | The path or directory of the [`.mjmlconfig` file](#community-components) | `process.cwd()`
useMjmlConfigOptions | Allows to use the `config` attribute from `.mjmlconfig` file | false
minifyOptions | Options for html minifier, see [mjml-cli documentation](https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md) for more info | {"collapseWhitespace": true, "minifyCSS": false, "removeEmptyAttributes": true}
juicePreserveTags | optional setting when inlining css, see [mjml-cli documentation](https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md) for more info | NA
option | unit | description | default value
----------------------- |---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |---------------
fonts | object | Default fonts imported in the HTML rendered by HTML | See in [index.js](https://github.com/mjmlio/mjml/blob/master/packages/mjml-core/src/index.js#L36-L44)
keepComments | boolean | Option to keep comments in the HTML output | true
beautify | boolean | Option to beautify the HTML output | false
minify | boolean | Option to minify the HTML output | false
validationLevel | string | Available values for the [validator](https://github.com/mjmlio/mjml/tree/master/packages/mjml-validator#validating-mjml): 'strict', 'soft', 'skip' | 'soft'
filePath | string | Full path of the specified file to use when resolving paths from [`mj-include` components](#mj-include) | '.'
mjmlConfigPath | string | The path or directory of the [`.mjmlconfig` file](#community-components) | `process.cwd()`
useMjmlConfigOptions | boolean | Allows to use the `config` attribute from `.mjmlconfig` file | false
minifyOptions | object | Options for html minifier, see [mjml-cli documentation](https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md) for more info | `{"collapseWhitespace": true, "minifyCSS": false, "removeEmptyAttributes": true}`
juicePreserveTags | boolean | Optional setting when inlining css, see [mjml-cli documentation](https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md) for more info | NA

## API

A free-to-use MJML API is available to make it easy to integrate MJML in your application. Head over [here](https://mjml.io/api) to learn more about the API.
A free-to-use MJML API is available to make it easy to integrate MJML in your application. Head
over [here](https://mjml.io/api) to learn more about the API.
7 changes: 6 additions & 1 deletion packages/mjml-cli/src/client.js
View file
Expand Up @@ -95,6 +95,10 @@ export default async () => {
version: {
alias: 'V',
},
noStdoutFileComment: {
type: 'boolean',
describe: 'Add no file comment to stdout',
},
})
.help()
.version(`mjml-core: ${coreVersion}\nmjml-cli: ${cliVersion}`)
Expand Down Expand Up @@ -316,7 +320,8 @@ export default async () => {
break
}
case 's': {
Promise.all(convertedStream.map(outputToConsole))
const addFileHeaderComment = !argv.noStdoutFileComment
Promise.all(convertedStream.map(converted => outputToConsole(converted, addFileHeaderComment)))
.then(() => (process.exitCode = EXIT_CODE)) // eslint-disable-line no-return-assign
.catch(() => (process.exitCode = 1)) // eslint-disable-line no-return-assign
break
Expand Down
10 changes: 8 additions & 2 deletions packages/mjml-cli/src/commands/outputToConsole.js
View file
@@ -1,4 +1,10 @@
export default ({ compiled: { html }, file }) =>
export default ({ compiled: { html }, file }, addFileHeaderComment) =>
new Promise((resolve) => {
process.stdout.write(`<!-- FILE: ${file} -->\n${html}\n`, resolve)
let output = ''
if(addFileHeaderComment) {
output = `<!-- FILE: ${file} -->\n`
}
output += `${html}\n`

process.stdout.write(output, resolve)
})

0 comments on commit 9ecacf6

Please sign in to comment.