Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/filiph/selfimproving-dev

The Self-Improving Developer book.
https://github.com/filiph/selfimproving-dev

Last synced: 6 days ago
JSON representation

The Self-Improving Developer book.

Awesome Lists containing this project

README 

        
Bob Nystrom started this. He wrote his excellent [Game Programming Patterns][]

book completely in the open. He showed us that it's possible to offer great

content for free *and at the same time* become a fancy published author.

Then he had the audacity of following it up 

with (possibly an even better book!) [Crafting Interpreters][]. The nerve!

 

I just took the open source tooling from [Bob's upstream project][] and

started my own book, _The Self-Improving Developer_, which is based on my

blog about intermediate software engineering topics.



You can find the site here: [selfimproving.dev][].



[Game Programming Patterns]: https://gameprogrammingpatterns.com/

[Crafting Interpreters]: https://craftinginterpreters.com/

[selfimproving.dev]: https://selfimproving.dev/



## License



[Bob's upstream project][] is double-licensed. It uses MIT for the tooling and

CC BY-NC-ND 4.0 for the "content files" (the text files, the SCSS styling,

and so on). 



[Bob's upstream project]: https://github.com/munificent/craftinginterpreters



This project stripped all of those content files and left only

the tooling and the scaffold. If you want that, go to the 

[`just tooling` branch][]. _That_ code is fully MIT-licensed. 

You can start your own book.



[`just tooling` branch]: https://github.com/filiph/selfimproving-dev/tree/just-tooling



After that commit, I started to add my own content, which is CC BY-NC-SA 4.0.



## Build



### Prerequisites



* POSIX environment

* [Dart][] SDK installed



[dart]: https://dart.dev/



Run the following once.



```sh

$ make get

```



This downloads all the packages used by the scripts in `/tools`.



### Writing



Bob:



> The Markdown and snippets of source code are woven together into the final

HTML using a hand-written static site generator that started out as a [single 

tiny Python script][py] for [my first book][gpp] and somehow grew into 

something approximating a real program.



[py]: https://github.com/munificent/game-programming-patterns/blob/master/script/format.py

[gpp]: http://gameprogrammingpatterns.com/



> The generated HTML is committed in the repo under `site/`. It is built from a

combination of Markdown for prose, which lives in `book/`, and snippets of code

that are weaved in from the Java and C implementations in `java/` and `c/`. (All

of those funny looking comments in the source code are how it knows which

snippet goes where.)



> The script that does all the magic is `tool/bin/build.dart`. You can run that

directly, or run:



> ```sh

> $ make book

> ```



> That generates the entire site in one batch. If you are incrementally working

on it, you'll want to run the development server:



> ```sh

> $ make serve

> ```



> This runs a little HTTP server on localhost rooted at the `site/` directory.

Any time you request a page, it regenerates any files whose sources have been

changed, including Markdown files, interpreter source files, templates, and

assets. Just let that keep running, edit files locally, and refresh your

browser to see the changes.



#### Chapter ordering



You specify which chapters get published and in what order by modifying

the `tool/lib/src/book_contents.dart` file.



## Repository Layout



*   `asset/` – Sass files and mustache templates used to generate the site.

*   `book/` - Markdown files for the text of each chapter.

*   `build/` - Intermediate files and other build output (except for the site

    itself) go here. Not committed to Git.

*   `site/` – The final generated site. The contents of this directory directly

    mirror the output of `build.dart`. Most content here is generated by this

    script, but fonts, images, and JS only live here. Everything is committed,

    even the generated content.

*   `tool/` – Dart package containing the build, test, and other scripts.



## Useful hints



### Deployment



The site is deployed on Firebase Hosting.



```

make deploy

```



### Building web scripts



There are some scripts written in Dart that make the web reading experience

a bit better. To build one, do something like this:



```sh

dart2js asset/scripts/index.dart -o site/index.dart.js -m -O4 --csp

```



### Converting from HTML to Markdown



To convert from HTML to Markdown using `pandoc`, do this:



```sh

pandoc -i some_file.html -o book/final-article-name.md 

```



On a Mac and with some HTML in your clipboard:



```sh

pbpaste | pandoc -f html -t gfm --shift-heading-level-by=-1 -o book/final-article-name.md

```