Skip to content

rubenwardy/minetest_modding_book

Repository files navigation

Minetest Modding Book

Build status
Read Online

Book written by rubenwardy. License: CC-BY-SA 3.0

Finding your way around

  • _data/ - Contains list of languages
  • _layouts/ - Layouts to wrap around each page.
  • static/ - CSS, images, scripts.
  • _<lang>/
    • <section>/ - Markdown files for each chapter.

Contributing chapters

  • Create a pull request with a new chapter in markdown.
  • Write a new chapter in the text editor of your choice and send them to me.

I'm happy to fix the formatting of any chapters. It is the writing which is the hard bit, not the formatting.

Chapter and Writing Guide

Grammar and such:

  • British English, except when referring common code words like color and initialize.
  • Prefer pronounless text, but you if you must. Never we nor I.
  • Titles and subheadings should be in Title Case.
  • References to code (such as function names) should be formatted as `inline-code`.
  • Italics used for emphasis, not necessarily for technical words.
  • Full stops and correct punctionation, except for lists without full sentences.

Formatting:

  • Do not rely on anything that isn't printable to a physical book.
  • Any links must be invisible - ie: if they're removed, then the chapter must still make sense.
  • Table of contents for each chapter with anchor links.
  • Add your turns to the end of a chapter when relevant.

Making a Chapter

To create a new chapter, make a new file in _en/section/. Name it something that explains what the chapter is about. Replace spaces with underscores ( _ )

---
title: Chapter Name
layout: default
root: ..
idx: 4.5
long_notice:
  level: tip
  title: This is a long tip!
  message: This is a very long tip, so it would be unreadable if
           placed in the main body of the chapter. Therefore,
           it is a good idea to put it in the frontmatter instead.
---

## Chapter Name

Write a paragraph or so explaining what will be covered in this chapter.
Explain why/how these concepts are useful in modding

* [List the](#list-the)
* [Parts in](#parts-in)
* [This Chapter](#this-chapter)

## List the

{% include notice.html notice=page.long_notice %}

Paragraphs

\```lua
code
\```

## Parts in

## This Chapter

Commits

If you are editing or creating a particular chapter, then use commit messages like this:

Getting Started - corrected typos
Entities - created chapter

Just use a normal style commit message otherwise.

Adding a new language

  1. Copy _en/ to your language code
  2. Add entry to _data/languages.yml
  3. Add entry to collections in _config.yml
  4. Add your language to the if else in layouts/default.html
  5. Translate your language code folder (that you made in step 1) You can translate the file paths, just make sure you keep any ids the same.

Using Jeykll

I use Jekyll 3.8.0

# For Debian/Ubuntu based:
sudo apt install ruby-dev
gem install jekyll github-pages

Building as a website

You can build it as a website using Jekyll

$ jekyll build

Goes to _site/

Webserver for Development

You can start a webserver on localhost which will automatically rebuild pages when you modify their markdown source.

$ jekyll serve

This serves at http://localhost:4000 on my computer, but the port may be different. Check the console for the "server address"