Replies: 1 comment 2 replies
-
@zeel01 we will follow up shortly with more detailed ideas, but I think this discussion has some of the answer you are looking for: #54 (comment) |
Beta Was this translation helpful? Give feedback.
2 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
I've been trying to come figure out a way to implement this for a while, and it seems like it's nearly possible but only if I override the standard transform functions for built-in Nodes, which seems like a bad way of going about it.
So I would either like some advice on how I might accomplish this, or I would like to suggest an API feature that would make this easy to accomplish.
The Goal
I'm trying to convert some existing documentation that is written in plain HTML into a more readable and easier to maintain Markdown format. This documentation involves a number of products, and in some cases different manufacturers of the same product will require slightly different instructions. This is handled in the existing docs by adding some extra classes to elements (mainly paragraphs, headings, and sections) that only apply for certain manufacturers. This looks something like:
Existing scripts on the site will control which elements are shown depending on the classes they bare.
It is not desirable to modify the way the page actually functions, I just want to be able to render Markdown into HTML that is compatible with the existing code of the rest of the site. I can't swap out this system for using
{% if %}
or anything like that, I need to render the markup so that it works correctly.First Approach
The first thing I did, which was a little tricky to figure out from the docs, was implement a new
Tag
calledmake
that will render a<section>
around its children and bare the correct classes:This will output:
This works! But while it's good if the section has multiple paragraphs within it, it's a little too verbose for single paragraphs, and makes the document a little messy looking. Not to mention that it results in unnecessary amounts of nesting in the output.
Desired Approach
What I would like to see, is something more like this:
This actually almost works, but the output is:
Obviously
make
isn't the attribute I want (I wantclass=
), and I want to addmake-
to the class names.Custom Attributes
With custom attributes, I can add a transform to the attribute which will let me modify the input strings and prefix them with
make-
, but can't (as far as I can tell) change the attribute name or mutate a different attribute.Not being able to change the attribute name is disappointing in and of itself, since to be spec-compliant HTML, custom attributes should be prefixed with
data-
, but in Markdown it's nice to allow them without the prefix. It would be great if there were an easy way to accomplish this without...Custom Tag Transformer
When I made the
make
tag I could do all the things I wanted - modify the attribute values, move the values to an attribute with a different name, use the data from the attributes to modify the values of other existing attributes, etc. The built-in heading even uses an attribute to modify the name of the HTML tag that it renders.The problem is, adding a custom transformer is fine for a custom tag, but doing it to built-in Nodes like paragraph, heading, etc is a bit of an issue. I think I could actually do this by passing an override for everything as the config object, but that seems like a foolish approach.
Potential Solutions
First and foremost... I might be missing something! So it may be reasonably feasible to do what I want, and I'm just not seeing it. But assuming that I'm correct and there isn't a really good way to do this...
Annotation Functions
One way that could probably handle this without all that much fuss, would be use a function like this:
At the moment,
make()
is only going to receive the string"some_brand"
as a parameter, along with theconfig
object. But it would be really cool if, when used in an annotation, a function would receive the preceding AST Node as its first parameter. In this way, the function could not only transform the parameter it is being passed, but also the Node that is being annotated. This would make functions far more powerful and useful.More Powerful Attribute Transformers
Attributes transformers just can't do a whole lot, it would be really nice if in addition to receiving their own values and the config object, if attributes would also receive their parent Node, which would allow them to manipulate not only themselves but other attributes, or even transform the children of their node.
Global Attribute Additions
I noticed that there is a
globalAttributes
object which containsclass
andid
attribute handling, and this is merged with the custom attributes on a given tag. It would be super useful if there were an option to add to this via the config object, allowing a custom attribute to be added to all nodes and tags, not just custom tags, without needing to jump through any additional hoops.Beta Was this translation helpful? Give feedback.
All reactions