update markdownlint headers to match doc

[rashmi43]

Description

Fixes: #15148

Reviewers

• Ambient
• [X ] Docs
• Installation
• Networking
• Performance and Scalability
• Extensions and Telemetry
• Security
• Test and Release
• User Experience
• Developer Infrastructure
• Localization/Translation

[istio-policy-bot]

😊 Welcome! This is either your first contribution to the Istio documentation repo, or
it's been a while since you've been here. A few things you should know:

• You can learn about how we write and maintain documentation, our style guidelines,
  and the available web site features by visiting Contributing to the Docs.

• In the next few minutes, an automatic preview of your change will be built with
  a full copy of the istio.io website. You can find this preview by clicking on
  the Details link next to the deploy/netlify entry in the status section of this
  page.

• We care about quality, so we've put in place a number of checks to ensure our documentation
  is top-notch. We do spell checking, sanitize the Markdown, ensure all hyperlinks point to a
  valid location, and more. If your PR doesn't pass one of these checks, you'll see a red X in the
  lint_istio.io entry in the status section. Click on the Details link to get a list of the
  problems with your PR. Fix those problems and push an update; this will automatically re-run the
  tests. Hopefully this time everything will be perfect!

• Once your changes are accepted and merged into the repository, they will initially show up
  on https://preliminary.istio.io. The changes will be published to https://istio.io
  the next time we do a major release (which typically happens every 3 months or so).
  To publish them sooner, add a cherrypick/release-x.xx label, where x.xx is the current
  release of Istio.

Thanks for contributing!

Courtesy of your friendly welcome wagon.

[linux-foundation-easycla]

• ❌ - login: @rashmi43 / name: Rashmi Khanna . The commit (07072a2) is not authorized under a signed CLA. Please click here to be authorized. For further assistance with EasyCLA, please submit a support request ticket.

[istio-testing]

Hi @rashmi43. Thanks for your PR.

I'm waiting for a istio member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[craigbox]

@rashmi43 Thanks for this, but the issue in question was asking to change the engine we use, not the configuration for the current one.

The change youve proposed would actually break every doc in istio.io, as they would all expect to start with a single # heading, where they currently start with a ## heading.

[rashmi43]

thanks for your comments, how can I go about engine change?
By defining a new rule file that uses the new engine? If you can break it down for me I can try to make the engine change.

[craigbox]

You would need to learn how the current script/build tools use the Ruby version of markdownlint, update them to package and use the Node.JS version, and then update the configuration to match our existing rules.

You may also need to do a mass update of the docs to fix any behaviour we can't configure around.

If you are interested in doing this, then consider dropping by #docs on the Istio slack.

[rashmi43]

You would need to learn how the current script/build tools use the Ruby version of markdownlint, update them to package and use the Node.JS version, and then update the configuration to match our existing rules.

You may also need to do a mass update of the docs to fix any behaviour we can't configure around.

If you are interested in doing this, then consider dropping by #docs on the Istio slack.

sure I will take this up