---

Replace API, changelog, and other data within markdown files, in place.

A Gulp plugin to replace intradoc template placeholders within markdown files (lodash-like template placeholders as markdown comments) without temporary or additional files, on the spot, in a reusable way.

---

🤔 Why?

• In place/on the spot replacement without temporary / additional files

• Reusability

• Simplicity

• 1.: It's more intuitive for everyday use, when dealing with durations ❤️:

  // general job cycle
  const cycle = duration('36 hours') // === 129600000 in milliseconds
  
  // movie playtime
  const length = duration('2h 41m') // === 9660000 in milliseconds
  
  // will log out "It is time!" in ~60,000 milliseconds
  setTimeout(() => console.log('It is time!'), duration('1 min'))
  
  // delays the execution for ~15,000 milliseconds
  await delay(duration('15 seconds'))

• 2.: It's easier, when handling larger or more complex durations 💪:

  // custom notification set manually by a user
  const notifyIn = duration('24 hours 36 minutes 49 seconds') // === 88609000  
  
  // cookie will expire in 7776000000 milliseconds from now
  const date = new Date(Date.now() + duration('90 days'))
  document.cookie = 'value=42;expires=' + date.toUTCString() + ';path=/')  
  
  // 24192000000 milliseconds from now
  User.update(
    { logged_out_warn_time: Date.now() + duration('280 days'), },
    { where: { id } }
  )

• 3.: It's highly configurable and the inputs are cached :

  // custom return unit with a default fallback
  duration('42 hours', '1 hour', { unit: 'seconds' }) // === 151200 in seconds
  
  // create a custom duration function with predefined arguments
  const custom = createCustom(0, '1 day', { unit: 'seconds' })
  
  // will return the given duration in seconds ({ unit: 'seconds' })
  custom('1 hour') // === 3600 in seconds

📦 Installation

• NPM:

  npm install @zengulp/intradoc-replacer --save-dev

• Yarn:

  yarn add @zengulp/intradoc-replacer --dev

☕ Usage

Intradoc placeholders are markdown comments with similar syntax to lodash templates.

Notice the 2 markdown comments under the Usage and API section below. After you ran your Gulp script, the given API data will be placed inside these 2 placeholders without removing them from the file.

Since intradoc placeholders are meant to be reusable, after processing, these intradoc placeholders will be still present in the markdown file for later reusability, but they will be invisible, when displaying / rendering the markdown file.

Only the content of these placeholders will be visible, as they are essentially just markdown comments.

In your markdown file (e.g.: README.md):

# Example Markdown File Title

This is an example `.md` file with 3 sections and an intradoc placeholder.

## Install

...

## Usage and API

<!--- <% API --->
old API documentation...
<!--- API %> --->

## License

...

In your Gulp script (e.g.: gulpfile.js):

const gulp = require('gulp')
const replacer = require('@zengulp/intradoc-replacer')

gulp.task('build:readme', async () => {
  gulp
    .src('./README.md')
    .pipe(replacer({ API: 'new API documentation...' }))
    .pipe(gulp.dest('./README.md'))
})

The processed markdown file after running the build:readme Gulp task:

Notice the 2 intradoc placeholders are still present in the file for later reusability. When displaying the markdown file, only their content will be visible, as these 2 placeholders are just markdown comments.

# Example Markdown File Title

This is an example `.md` file with 3 sections and an intradoc placeholder.

## Install

...

## Usage and API

<!--- <% API --->
new API documentation...
<!--- API %> --->

## License

...

💻 API

---

⭐ Related

Check out the official website for more tools, utilities, and packages.

Find more @zengulp packages on NPM and GitHub.

🍻 Contribution

Any contribution is highly appreciated. To get going, check out the contribution guidelines.

Thank you and have fun!

©️ License

ISC @ Richard King