typescript-book/tools

Tools for Working with Markdown Books

If you're working with Markdown books, here are some essential tools and commands to help you streamline your workflow.

Installation

Before you begin, ensure you have Node.js installed. To set up the required dependencies, use the following commands:

In folder tools and website:

nvm use
npm install

brew install pandoc
brew install epubcheck
brew install --cask calibre

Commands

Use make to run the main commands:

• make format: Format Markdown files for books.
• make check: Run several checks to ensure the Markdown files are valid.
• make website: Create different Markdown pages for the website.
• make website-preview: Build and preview website locally.
• make website-deploy: Build and deploy website to GitHub Pages.
• make books: Create .epub books.

Formatting

Consistent code formatting is crucial. To format all TypeScript snippets, we use Prettier. Execute the following command for formatting:

npm run format

Compilation

To compile TypeScript snippets within the Markdown files, utilize the following command:

npm run compile

Linting

To ensure that your Markdown files adhere to proper formatting rules, use the linting command:

npm run lint:md

Linting and Formatting

For a comprehensive process that includes linting all Markdown files, applying Prettier formatting to all TypeScript snippets, and compiling them using TypeScript, use the following command:

npm run check

The project uses the Markdown All in OneVisual Studio Code extension to automatically update the table of contents.

Use the following command to install it:

code --install-extension yzhang.markdown-all-in-one

Skipping Compilation

If you have specific snippets in the Markdown files that you don't want to compile, simply add <!-- skip --> just before the TypeScript demarcation for those snippets.

Epub Generation

To generate Epub files from your Markdown books, navigate to the tools folder and run the following command:

make-books.sh

After generating the Epub files, thoroughly test them, and once you're satisfied with the results, commit the changes.

These tools will assist you in efficiently working with Markdown books and ensure a smooth and organized process. Happy writing!

Debug EPUB Issues

To debug the EPUB files you create, follow these steps:

First, download and install Sigil. You can use the following command to install Sigil:

brew install --cask sigil

Next, run an EPUB check to validate your EPUB file. For example:

epubcheck ../downloads/typescript-book.epub

Finally, open the EPUB file using Sigil for detailed inspection.

How to Contribute to This E-Book

To contribute to this e-book, follow these steps:

• Update the main Markdown file with your changes.
• Run make check to ensure the linter and other checks pass.
• Preview the website locally with make website-preview to make sure it works as expected.
• Generate the e-books by running make books.
• Submit your PR and share your awesome contributions!