Comments (4)
Note that this strange behavior is not reproduced in the sandbox provided here https://mystmd.org/, for which we get the more reasonable output
<h3>Heading 3</h3>
<h2>Heading 2</h2>
<h4>Heading 4</h4>
Therefore I think it can be considered as a real bug of MyST-Parser...
from myst-parser.
Hey @paugier , this is not trivially possibly, without upstream modification to docutils/sphinx
docutils stores documentation in a nested AST:
# H1
## H2
### H3
creates
<section>
H1
<section>
H2
<section>
H3
No information on the #
number is actually stored or used by the docutils/sphinx HTML writers (since restructuredtext does not have this concept)
If you wanted to start at greater than #
, like:
## H2
### H3
#### H4
Then it will simply get stored as:
<section>
H2
<section>
H3
<section>
H4
with docutils, the HTML writer has the options; rst2html5 --no-doc-title --initial-header-level=2
,
which you could then use to "retrieve" the original heading levels
Alternatively, you could modify myst-parser, to capture the #
count, e.g.
<section level=2>
H2
<section level=3>
H3
<section level=4>
H4
but then you would also need to modify the docutils/sphinx writer(s) to utilise this attribute.
For your case though, it is even more problematic, what you maybe need is for myst-parser to create "phantom" sections, to allow for the correct nesting:
### Heading 3
## Heading 2
#### Heading 4
<section phatom>
<section phatom>
<section>
Heading 3
<section>
Heading 2
<section phatom>
<section>
Heading 4
You would then need to modify docutils/sphinx, to handle these phantom sections, e.g. skipping them in the HTML creation
is not reproduced in the sandbox provided her
Therefore I think it can be considered as a real bug of MyST-Parser...
mystmd is a separate entity to myst-parser 🙃
from myst-parser.
See also jgm/djot#294, I was interested what they have to say on it
from myst-parser.
Thanks @chrisjsewell for your explanation. So it is not as simple as I thought. For the Pelican plugin using myst (myst-reader), the most important issue is that most of the time the first heading uses ##
(since the title is in the frontmatter).
I think we already use --initial-header-level=2
for docutils but we clearly have an issue with Sphinx.
Then, the question is which package/tool should be modified to fix our issue. I guess the simplest quick and dirty solution for myst-reader is to produce the html with sphinx and do few replacements when we detect it's necessary.
But we could also ask sphinx to implement --initial-header-level=2
even if they don't need that for their standard usage. Or using <section level=2>
which would be the cleanest solution but requires quite a lot of changes I guess.
I would be interested to know what do you think @chrisjsewell.
Aside question: do you plan to have a myst -> html converter independent of docutils and sphinx, but that would support few important (for myst) sphinx extensions? It would be great!
from myst-parser.
Related Issues (20)
- Equation label of math not work before `make clean` when math_numfig=True HOT 7
- Support sphinx 7.3 - use default config value types HOT 2
- `end-before` parameter thinks it has no argument HOT 3
- More than one target found for 'myst' cross-reference [myst.xref_ambiguous] HOT 3
- $$ equation reference is not identified unless preceded by a blank line HOT 3
- no syntax to create line_block (hardbreak creates paragraph with raw linebreaks) HOT 4
- Issue on page /syntax/admonitions.html - In example, class should be space separated not comma HOT 3
- Include directive does not consider parser option HOT 2
- replacement of "." in headings for slugs HOT 1
- Test regressions with Sphinx 7.3.7 HOT 2
- Missing newline from doc HOT 5
- For v3.0.1: indented directive options no longer recognised HOT 7
- For v3.0.1: If the last directive option has an empty value then it is omitted HOT 5
- Add `:tag:` Option for Custom Equation Numbering in `{math}` Directives HOT 1
- Add warning for invalid footnotes reference (and unused definitions) HOT 3
- Add example config.yml entries for autodoc-2 HOT 1
- More Complete Info about Auto Documentation HOT 1
- Substitution in Block doesn't seem to work in Live Preview HOT 1
- Executablebooks
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
Heading 2
`from myst-parser.