Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Docz - It has never been so easy to document your things!

Docz - It has never been so easy to document your things!

Pedro Nauck

June 16, 2018
Tweet

More Decks by Pedro Nauck

Other Decks in Technology

Transcript

  1. It has never been so easy to document your things!

    View full-size slide

  2. Pedro Nauck
    @pedronauck

    View full-size slide

  3. ⚙ Need setup
    ⛏ Hard/impossible to customize
    # Complex codebase
    Heavy and slow
    Pain

    View full-size slide

  4. Zero config and easy
    ⚡ Blazing Fast
    Easy to customize
    MDX Based
    Pluggable
    Typescript and Flow Support
    Solution

    View full-size slide

  5. Zero-config
    ➡ Run without complex configurations
    ➡ Easy to setup and use
    ➡ No strict architectures

    View full-size slide

  6. Blazing fast
    ➡ Fast build with webpack 4
    ➡ Automatic code splitting
    ➡ Hot reload that works

    View full-size slide

  7. Easy to customize
    ➡ Create your own style
    ➡ Share and create themes

    View full-size slide

  8. MDX Based
    ➡ Markdown with components
    ➡ Easy to write and understand
    ➡ Built-ins components
    ➡ Remark and Rehype ecosystem

    View full-size slide

  9. Is a tree representation of the abstract
    syntactic structure of source code written in a
    programming language
    AST

    View full-size slide

  10. unified is an interface for processing text using syntax trees.

    View full-size slide

  11. 1. Parse: Text => MDAST
    2. Transpile: MDAST => MDXAST
    3. Transform: MDX/Remark plugins applied to AST
    4. Transpile: MDXAST => MDXHAST
    5. Transform: Hyperscript plugins applied to AST
    6. Transpile: MDXHAST => JSX
    Transpilation Flow

    View full-size slide

  12. Pluggable
    ➡ Third party integration
    ➡ Easy to reuse and install

    View full-size slide

  13. Typescript and Flow
    ➡ Zero config typescript and flow support

    View full-size slide

  14. How it Works

    View full-size slide

  15. YOUR DOCS
    THEME
    BUNDLER
    PLUGINS
    ENTRIES PARSE
    PROJECT CONFIGURATION

    View full-size slide

  16. Write app files ‣ Write app files using node file system for bundle
    ‣ Render theme, wrappers and router
    Start devserver
    ‣ Start bundler dev server
    ‣ Get configuration from plugins
    ‣ Watch mdx and configuration file using chokidar
    Create data ‣ Server communication with Websockets
    Parse entries ‣ Get meta information using AST parsing

    View full-size slide

  17. ➡ Testing documentation generation
    ➡ Vue, Preact and Inferno integration
    ➡ Static builds based on routes (SSR)
    ➡ Render popups on the fly (action logger)
    ➡ Fetch data (getInitialData)
    ➡ …

    View full-size slide

  18. Some Numbers

    View full-size slide

  19. What I’ve Learned

    View full-size slide

  20. ✅ Create something that you're really going to use
    ✅ Explore the current pains and work upon them
    ✅ Work hard to build something good
    ✅ Be patient, your project isn’t a startup
    ✅ Try to find the way between an MVP and a perfect project
    ✅ Make a badass announcement and documentation

    View full-size slide

  21. https://github.com/pedronauck/docz
    Give us some star

    View full-size slide