5 ms·

I think a good example is all of the wonderful documentation that's been created with mdBook. Heck, the Rust book was written with it, and they also made a pri

by paholg 2y ago

I think a good example is all of the wonderful documentation that's been created with mdBook. Heck, the Rust book was written with it, and they also made a print edition, so maybe markdown is enough even for that. https://github.com/rust-lang/mdBook https://github.com/rust-lang/mdBook

steveklabnik 2y ago
Carol put in a tremendous amount of work to build tooling to go between Markdown and Docx. The publishers used the docx versions for print. That doesn’t mean that I think Markdown is inadequate or the wrong decision, but it’s not just a “write in Markdown and you’re good” sort of situation.
- paholg 2y ago
  Ah, good to know! Is that tooling public anywhere, or was it pretty tailor-made just for the Rust book?
  - steveklabnik 2y ago
    Both public and tailor-made: https://github.com/rust-lang/book/tree/main/tools https://github.com/rust-lang/book/tree/main/tools
    - paholg 2y ago
      Awesome! You and Carol rock!
      - steveklabnik 2y ago
        Thanks! She gets 100% of the credit in this case though :)
    - brnt 2y ago
      I can find here the process of converting docx to md, but not the reverse. I see the material is checked into the repo in both formats. Does that mean the docx's are your master, and you generate the markdown from it for diffing and building HTML? I'm investigating how to switch an organisation away from a docx-only mess of a documentation system, and it looks like you might have found a process that'd work for us, and let people keep using docx if they have to. I wonder what all those binary blobs do to the git repo though. Thanks for any info!
      - steveklabnik 2y ago
        You'd have to ask Carol, with the way we split the work, she handled all of this. From my perspective, the markdown was the master copy. Sorry I can't be of more help!
Terretta 2y ago
The link below (https://github.com/rust-lang/book/tree/main/tools https://github.com/rust-lang/book/tree/main/tools) could imply the book was written as Word .docx with named styles, which enabled transformation into markdown for the mdBook?

by paholg 2y ago

steveklabnik 2y ago

Carol put in a tremendous amount of work to build tooling to go between Markdown and Docx. The publishers used the docx versions for print. That doesn’t mean that I think Markdown is inadequate or the wrong decision, but it’s not just a “write in Markdown and you’re good” sort of situation.

paholg 2y ago
Ah, good to know! Is that tooling public anywhere, or was it pretty tailor-made just for the Rust book?
- steveklabnik 2y ago
  Both public and tailor-made: https://github.com/rust-lang/book/tree/main/tools https://github.com/rust-lang/book/tree/main/tools
  - paholg 2y ago
    Awesome! You and Carol rock!
    - steveklabnik 2y ago
      Thanks! She gets 100% of the credit in this case though :)
  - brnt 2y ago
    I can find here the process of converting docx to md, but not the reverse. I see the material is checked into the repo in both formats. Does that mean the docx's are your master, and you generate the markdown from it for diffing and building HTML? I'm investigating how to switch an organisation away from a docx-only mess of a documentation system, and it looks like you might have found a process that'd work for us, and let people keep using docx if they have to. I wonder what all those binary blobs do to the git repo though. Thanks for any info!
    - steveklabnik 2y ago
      You'd have to ask Carol, with the way we split the work, she handled all of this. From my perspective, the markdown was the master copy. Sorry I can't be of more help!

Terretta 2y ago

The link below (https://github.com/rust-lang/book/tree/main/tools https://github.com/rust-lang/book/tree/main/tools) could imply the book was written as Word .docx with named styles, which enabled transformation into markdown for the mdBook?