Chris Sewell

Linking https://github.com/executablebooks/MyST-Parser/issues/69

> Do we need to be as formal as UML diagrams? yep I'm definitely +1 for diagramming the proposed before/after It doesn't have to be anything formal, just sketch it...

> A related topic is that extensions tend to store state by dynamically adding attributes to the above objects. We should have a cleaner way to handle state of extensions....

Heya, you do realise this is used by one of sphinx's own extensions 😅: https://github.com/sphinx-doc/sphinxcontrib-jsmath/blob/19763d7fc9ebb29eb2f325fef0bc6f067907a233/sphinxcontrib/jsmath/__init__.py#L70 it is also used here: https://github.com/jbms/sphinx-immaterial/blob/69e685aedd338f6766ddb5bae9b2189d2e7a6898/sphinx_immaterial/local_mathjax.py#L28 Calling a method internal, just because it is undocumented,...

> I don't think it holds true for old code, where marking names as private was less deliberate. I really think it does; users will not care about your standards,...

cheers @AA-Turner love it ❤️ Haven't looked through in detail yet, but one request... can we link this to https://github.com/sphinx-doc/sphinx/pull/12361, and have the new `SphinxDirective` methods "ask" the parser how...

Oh and also, I don't know if if it was in your planning, but we could also add an inline parse method for `SphinxRole`

> I think this is automatic, as we use the current parser (by using the state machine directly) This assumes that the parser has a state machine, which is actually...

@AA-Turner correct me if I'm wrong, but in this PR you have essentially changed all occurrences of `self.state.nested_parse` to `self.parse_content_to_nodes`? But `nested_parse` defaulted to `match_titles=False`, whereas now `parse_content_to_nodes` uses `match_titles=True`....

> I do think in general that titles ought be allowed where possible where possible maybe, but I do want to emphasise that you cannot nest sections inside other nodes...