Add deprecation note for pedantic mode

[wooorm]

Closes GH-470.

pedantic mode is buggy. It won’t be in micromark. This PR warns users not to use it.

[ChristianMurphy]

Could we add a @deprecated annotation to pedanic in the typings?
And might we want to add a deprecation log in the code itself?

[wooorm]

I wanted to do a “soft” one first, just docs, to signal that the pedantic code is basically frozen for future issues or new users. Hoping the next major after this one will be micromark.

[ChristianMurphy]

Agreed, code wise I was thinking something like Node's depercate
https://github.com/nodejs/node/blob/1b1c2993a5bc9a64cb4d417509d2fc35a64182f4/lib/internal/util.js#L62-L102
Where it is a soft deprecation, but adds some logs to signal the incoming change, in case people haven't reviewed the docs.

[wooorm]

My plan was to be even softer mostly due to https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-transformer-remark/src/extend-node-type.js#L110 😬

[ChristianMurphy]

ah, that make sense.
CC'ing the Gatby team members who have recently worked on the remark integration to raise awareness.

/cc @pieh @sidharthachatterjee @wardpeet @DSchau