-
Notifications
You must be signed in to change notification settings - Fork 855
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add Documentation on Extension Configuration #1469
Conversation
@@ -82,6 +82,12 @@ __extensions__{: #extensions } | |||
|
|||
markdown.markdown(text, extensions=[MyExtClass(option='value')]) | |||
|
|||
To configure an officially supported extension, import its class and provide | |||
options when instantiating the extension. For example: | |||
:::python |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You need a blank line before the code block, otherwise it will be treated as a continuation of the previous paragraph.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you for the feedback! I have added a blank line before the code block to format it correctly.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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)])
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
No description provided.