Add Documentation on Extension Configuration

[sujaudd1n]

No description provided.

[mitya57]

You need a blank line before the code block, otherwise it will be treated as a continuation of the previous paragraph.

[waylan]

Also, this repeats information contained in the preceding paragraph. In fact, the previous example even includes an example of setting a config option. I don't see how adding this adds any value.

[sujaudd1n]

Thank you for the feedback! I have added a blank line before the code block to format it correctly.

[sujaudd1n]

From the preceding paragraph it is not clear how one can import official
extension class and configure it.

I think having a concrete example is a good idea.

[waylan]

I think having a concrete example is a good idea.

We do have one, in the example right before your inserted paragraph. The only difference is that it uses a custom made-up class name, and your uses an existing class. There is no value repeating another example. And the added paragraph simply repeats the information already stated in the preceding paragraph. There is no value here. However, if you think the existing language is unclear, a tweak to it to make it more clear would be fine. Otherwise I am inclined to close this.

[sujaudd1n]

I agree that the previous paragraph conveys a similar message. It would be beneficial to include an existing extension class in the example for better illustration. I'd love to hear your thoughts on the following modification.

:::python
from markdown.extensions import Extension
from markdown.extensions.codehilite import CodeHiliteExtension
class MyExtClass(Extension):
    # define your extension here...

markdown.markdown(text, extensions=[MyExtClass(option='value'), CodeHiliteExtension(linenums=True)])

[waylan]

So this is just basic Python. Any experienced Python user who sees an example of one can work out how to do the other. Therefore, I see no value in including both. The custom extension was chosen as that would presumably be the most common use-case for this as users generally use the name-based option (which is documented later) for the built-in extensions.

But maybe the problem is that I am not seeing things from the perspective of a new user. So, can you explain to me how your suggested change helps where the existing documentation does not?

[sujaudd1n]

Thank you for your feedback.

I encountered an issue while reading the documentation, as it was unclear how to transition from the example:

from markdown.extensions import Extension
class MyExtClass(Extension):
    # define your extension here...
markdown.markdown(text, extensions=[MyExtClass(option='value')])

to the more general case:

from markdown.extensions.codehilite import CodeHiliteExtension
markdown.markdown(text, extensions=[CodeHiliteExtension(linenums=True)])

Although some extensions provide code examples of how to do this, not all of them do. I believed that including an example at this point would eliminate any confusion.

However, I understand your perspective. If you don't see the value in this change, it's okay to close this pull request.