Namely, Pickled Meatballs

    @codedoc/core
    TypeScript icon, indicating that this package has built-in type declarations

    0.2.24 • Public • Published

    CODEDOC

    npm i -g @codedoc/cli

    CODEDOC is an open-source tool that helps you with creating beautiful and modern software documentation. It creates a JAMStack app from your markdown files that you can easily deploy on services such as GitHub Pages. Read the docs for more info.



    Installation

    npm i -g @codedoc/cli
    
    cd my-project
    codedoc init

    Read the docs for more info.



    Usage

    codedoc serve

    Modify your markdown files (by default in docs/md/, for example docs/md/index.md) and see changes in real time. When you are done, build your documentations for deployment:

    codedoc build

    and if you are for example using GitHub Pages, deploy by pushing:

    git add -A
    git commit -m "added docs"
    git push

    Read the docs for more info.



    Prior Work

    While there are multiple frameworks and tools that help with building websites from a bunch of markdown files, I will only focus on those who are specifically designed for writing documentation/wikis, since the rest naturally come with a configuration overhead. You can read this section for more info on CODEDOC's features compared to the works mentioned here.

    Jekyll

    A lot of the ideas of the workflow are shared between Jekyll and CODEDOC. The reason I created CODEDOC despite Jekyll being out there because:

    • Jekyll is a bit old-school and hence heavy handed by modern frontend standards (no component structure, etc),
    • Jekyll's themes are not up to modern standards, and it is quite some work to create new themes,
    • Jekyll is not yet specifically designed for documentation and project wikis (thats why GitHub has a separate wiki section for projects despite supporting Jekyll out of the box).

    GitBook

    GitBook is a nice SaaS built specifically for documentation and project wikis. However:

    • It lacks some essential features (such as code-snippet hints),
    • It hides some essential features behind a paywall (for example the dark mode), which hurts open-source projects,
    • It is not customizable enough for my taste.



    Acknowledgements

    The following tools and open-source libraries are used by CODEDOC, so shout-out to their creators/maintainers/collaborators:

    webpack
    Used by CONNECTIVE SDH as client-side code bundler. CONNECTIVE SDH is the basis of server-side/client-side rendering and components of CODEDOC.

    jsdom, jsdom-global
    Used by CONNECTIVE SDH for ease of HTML element creation on the server side.

    Marked.js
    Used by @connectv/marked as markdown processor (@connectv/marked enables using TSX-components for processing markdown and powers the custom components system).

    JSS
    Used by CONNECTIVE JSS Theme which is the themed-component library used by CODEDOC.

    Prism
    Used for syntax highlighting in code snippets.

    Color Hunt
    For picking the default colors (also thanks to Niyousha Karimi for helping on that front, besides helping with usability testing).

    RxJS
    Used by CONNECTIVE, CONNECTIVE HTML (which is the TSX-Component library behind CODEDOC components) for client-side interactions and RxLine for asynchronous build process.

    ts-node, ts-node-dev
    Used by the CLI to run the build process and watch over markdown/config files.

    Express
    Used for the local development server.

    ShellJS, chalk
    Powering the CLI and making it look nice.

    select
    Used for convenient copy-to-clipboard functionality.

    KaTeX
    Used for rendering LaTeX formulas.

    color
    Used for automatic color deduction/manipulation.

    Install

    npm i @codedoc/core

    DownloadsWeekly Downloads

    23

    Version

    0.2.24

    License

    MIT

    Unpacked Size

    1.23 MB

    Total Files

    823

    Last publish

    Collaborators

    • lorean.victor