Asciidoc and RST fall down because they act like Excel: a UI which expects its user to work through a tutorial on pivot tables. The success of Markdown comes fr

Asciidoc and RST fall down because they act like Excel: a UI which expects its user to work through a tutorial on pivot tables. The success of Markdown comes from knowing that its users don't want to spend any more time learning it than they spend learning how their bank website works. So you want to preserve that navigability. A source-reader isn't going to have the time to learn "conventions" like rails asks them to do. So for any deviations from markdown, you would want the reader of the source to be able to see how those are defined. I think the sweet spot would be markdown-biased JSX. The directory structure would be: - `/components` with two file to start: index.jsx, which would import the `Markdown` element from the library and re-export it. There would also be custom-component-example.jsx to demonstrate and document the interface expected by the renderer. Any custom components go in this directory. - `/theme` which has theme information across the whole site. If you want a different theme for a different part of the page, that is a different site - `/source` with a tree of mostly .md files, but occasionally .jsxmd files which tell the source-reader where the component was defined, but otherwise get out of the way. A .jsxmd file might look like this: ``` from '../../components' import Markdown, Aside; export default () => (<Markdown> ## JavaScript Resources The React documentation assumes some familiarity with programming in the JavaScript language. You don’t have to be an expert, but it’s harder to learn both React and JavaScript at the same time. We recommend going through this JavaScript overview to check your knowledge level. It will take you between 30 minutes and an hour but you will feel more confident learning React. <Aside> #### Tip Whenever you get confused by something in JavaScript, MDN and javascript.info are great websites to check. There are also community support forums where you can ask for help. </Aside> ## Practical Tutorial If you prefer to learn by doing, check out our practical tutorial. In this tutorial, we build a tic-tac-toe game in React. You might be tempted to skip it because you’re not into building games — but give it a chance. The techniques you’ll learn in the tutorial are fundamental to building any React apps, and mastering it will give you a much deeper understanding. </Markdown>) ```