Update the README
This commit is contained in:
rubenwardy
parent
d2c94dc825
commit
df31b86845
247
README.md
247
README.md
@ -1,53 +1,101 @@
|
|||||||
---
|
# Minetest Modding Book
|
||||||
title: README for Contributors
|
|
||||||
layout: default
|
|
||||||
---
|
|
||||||
|
|
||||||
## Welcome!
|
[Read Online](https://rubenwardy.com/minetest_modding_book/)
|
||||||
|
|
||||||
This project uses Jekyll to turn Markdown into HTML, but you don't need to
|
|
||||||
do that. You can just create Markdown files and pull request them. In fact,
|
|
||||||
you don't even need to use Markdown: send me a document via the forum PM, topic
|
|
||||||
or my email address (see my github profile).
|
|
||||||
It is the writing which is the hard bit, not the formatting.
|
|
||||||
|
|
||||||
Book written by rubenwardy.
|
Book written by rubenwardy.
|
||||||
License: CC-BY-SA 3.0
|
License: CC-BY-SA 3.0
|
||||||
|
|
||||||
## Why is this a GitHub repo, rather than a wiki?
|
|
||||||
|
|
||||||
I want to be able to review any changes to make sure that they
|
|
||||||
fit my idea of quality.
|
|
||||||
|
|
||||||
## Finding your way around
|
## Finding your way around
|
||||||
|
|
||||||
* `_data/` - Contains the navigation bar file.
|
* `_data/` - Contains list of languages
|
||||||
(a list of links and link text for the navbar.)
|
* `_layouts/` - Layouts to wrap around each page.
|
||||||
* `_includes/` - Contains HTML templates.
|
|
||||||
* `_layouts/` - You can safely ignore this.
|
|
||||||
* `static/` - CSS, images, scripts.
|
* `static/` - CSS, images, scripts.
|
||||||
* `<lang>/`
|
* `_<lang>/`
|
||||||
* `chapters/` - Markdown files for each chapter.
|
* `<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](https://rubenwardy.com/contact/).
|
||||||
|
|
||||||
|
I'm happy to fix the formatting of any chapters. It is
|
||||||
|
the writing which is the hard bit, not the formatting.
|
||||||
|
|
||||||
|
### Chapter Guidelines
|
||||||
|
|
||||||
|
* Prefer pronounless text, but `you` if you must. Never `we` nor `I`.
|
||||||
|
* 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 turn`s to the end of a chapter when relevant.
|
||||||
|
* Titles and subheadings should be in Title Case.
|
||||||
|
|
||||||
|
### 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 ( _ )
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
title: Chapter Name
|
||||||
|
layout: default
|
||||||
|
root: ..
|
||||||
|
idx: 4.5
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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
|
||||||
|
|
||||||
|
Paragraphs
|
||||||
|
|
||||||
|
{% highlight lua %}
|
||||||
|
code
|
||||||
|
{% endhighlight %}
|
||||||
|
|
||||||
|
## 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
|
## Adding a new language
|
||||||
|
|
||||||
* Add entry to `_data/languages.yml`
|
1. Copy `_en/` to your language code
|
||||||
* Add your language to the if else in `_includes/header.html`
|
2. Add entry to `_data/languages.yml`
|
||||||
* Copy `_en/` to your language code
|
3. Add entry to `collections` in `_config.yml`
|
||||||
* Translate your language code folder.
|
4. Add your language to the if else in `layouts/default.html`
|
||||||
You can translate the file paths, just make sure you keep any ids the same.
|
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
|
## Using Jeykll
|
||||||
|
|
||||||
I use [Jekyll](http://jekyllrb.com/) 2.5.3
|
I use [Jekyll](http://jekyllrb.com/) 3.8.0
|
||||||
|
|
||||||
# For Linux based:
|
# For Debian/Ubuntu based:
|
||||||
|
sudo apt install ruby-dev
|
||||||
$ sudo apt-get install ruby-dev
|
gem install jekyll github-pages
|
||||||
$ gem install jekyll
|
|
||||||
$ gem install jekyll-sitemap
|
|
||||||
|
|
||||||
# You may need to use sudo on the above commands
|
|
||||||
|
|
||||||
### Building as a website
|
### Building as a website
|
||||||
|
|
||||||
@ -67,132 +115,3 @@ rebuild pages when you modify their markdown source.
|
|||||||
|
|
||||||
This serves at <http://localhost:4000> on my computer, but the port
|
This serves at <http://localhost:4000> on my computer, but the port
|
||||||
may be different. Check the console for the "server address"
|
may be different. Check the console for the "server address"
|
||||||
|
|
||||||
## 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.
|
|
||||||
|
|
||||||
## Making a Chapter
|
|
||||||
|
|
||||||
To create a new chapter, make a new file in chapters/.
|
|
||||||
Name it something that explains what the chapter is about.
|
|
||||||
Replace spaces with underscores ( _ )
|
|
||||||
|
|
||||||
**Template**
|
|
||||||
|
|
||||||
{% raw %}
|
|
||||||
|
|
||||||
---
|
|
||||||
title: Player Physics
|
|
||||||
layout: default
|
|
||||||
root: ..
|
|
||||||
---
|
|
||||||
|
|
||||||
Introduction
|
|
||||||
------------
|
|
||||||
|
|
||||||
Write an paragraph or so explaining what will be covered in this chapter.
|
|
||||||
Explain why/how these concepts are useful in modding
|
|
||||||
|
|
||||||
* List the
|
|
||||||
* Parts in
|
|
||||||
* This chapter
|
|
||||||
|
|
||||||
Section
|
|
||||||
-------
|
|
||||||
|
|
||||||
Explaining the concept of something.
|
|
||||||
|
|
||||||
You can link to other chapters like this: [chapter title]({{ relative }}/chaptertitle/).//
|
|
||||||
Do it like Wikipedia, link words in a sentence but avoid explicitly telling the user to view it//
|
|
||||||
or click the link.
|
|
||||||
|
|
||||||
Mod Name
|
|
||||||
- init.lua - the main scripting code file, which is run when the game loads.
|
|
||||||
- (optional) depends.txt - a list of mod names that needs to be loaded before this mod.
|
|
||||||
- (optional) textures/ - place images here, commonly in the format modname_itemname.png
|
|
||||||
- (optional) sounds/ - place sounds in here
|
|
||||||
- (optional) models/ - place 3d models in here
|
|
||||||
...and any other lua files to be included by init.lua
|
|
||||||
|
|
||||||
Code snippets are tabbed one level in, except for lua snippets, which use a code highligter.
|
|
||||||
|
|
||||||
Section 2
|
|
||||||
---------
|
|
||||||
|
|
||||||
Explaining another concept
|
|
||||||
|
|
||||||
{% highlight lua %}
|
|
||||||
print("This file will be run at load time!")
|
|
||||||
|
|
||||||
minetest.register_node("mymod:node",{
|
|
||||||
description = "This is a node",
|
|
||||||
tiles = {
|
|
||||||
"mymod_node.png",
|
|
||||||
"mymod_node.png",
|
|
||||||
"mymod_node.png",
|
|
||||||
"mymod_node.png",
|
|
||||||
"mymod_node.png",
|
|
||||||
"mymod_node.png"
|
|
||||||
},
|
|
||||||
groups = {cracky = 1}
|
|
||||||
})
|
|
||||||
{% endhighlight %}
|
|
||||||
|
|
||||||
Use the highlight tags to highlight Lua code.
|
|
||||||
|
|
||||||
Section 3
|
|
||||||
---------
|
|
||||||
|
|
||||||
You should include plenty of examples. Each example should
|
|
||||||
be able to be installed in a mod and used. Don't do the thing where
|
|
||||||
you make the reading create the mod line-by-line, it is rather annoying
|
|
||||||
and good code can explain itself. Explaining line-by-line is needed in earlier chapters,
|
|
||||||
and when introducing new concepts.
|
|
||||||
|
|
||||||
### Mod Folder
|
|
||||||
mymod/
|
|
||||||
- init.lua
|
|
||||||
- depends.txt
|
|
||||||
|
|
||||||
|
|
||||||
default
|
|
||||||
|
|
||||||
{% highlight lua %}
|
|
||||||
print("This file will be run at load time!")
|
|
||||||
|
|
||||||
minetest.register_node("mymod:node",{
|
|
||||||
description = "This is a node",
|
|
||||||
tiles = {
|
|
||||||
"mymod_node.png",
|
|
||||||
"mymod_node.png",
|
|
||||||
"mymod_node.png",
|
|
||||||
"mymod_node.png",
|
|
||||||
"mymod_node.png",
|
|
||||||
"mymod_node.png"
|
|
||||||
},
|
|
||||||
groups = {cracky = 1}
|
|
||||||
})
|
|
||||||
{% endhighlight %}
|
|
||||||
|
|
||||||
Explain the code here, but there is no need to explain every single line.
|
|
||||||
Use comments and indentation well.
|
|
||||||
|
|
||||||
Your Turn
|
|
||||||
---------
|
|
||||||
|
|
||||||
* **Set Tasks:** Make tasks for the reader to do.
|
|
||||||
* **Start easy, get hard:** Start with easier ones, and work up to harder ones.
|
|
||||||
|
|
||||||
{% endraw %}
|
|
||||||
|
|
||||||
Please note that the above is a guideline on how to make good chapter, but isn't
|
|
||||||
exhustive and there are many exceptions. The priority is explaining the concepts
|
|
||||||
to the reader efficiently and in a way which is understandable.
|
|
||||||
|
|||||||
@ -30,5 +30,6 @@ Noticed a mistake, or want to give feedback? Make sure to tell me about it.
|
|||||||
|
|
||||||
* Create a [GitHub Issue](https://github.com/rubenwardy/minetest_modding_book/issues).
|
* Create a [GitHub Issue](https://github.com/rubenwardy/minetest_modding_book/issues).
|
||||||
* Post in the [Forum Topic](https://forum.minetest.net/viewtopic.php?f=14&t=10729).
|
* Post in the [Forum Topic](https://forum.minetest.net/viewtopic.php?f=14&t=10729).
|
||||||
* Send me a [PM](https://forum.minetest.net/ucp.php?i=pm&mode=compose&u=2051) on the forums.
|
* [Contact me](https://rubenwardy.com/contact/).
|
||||||
* Fancy contributing? [Read the README](../README.html).
|
* Fancy contributing?
|
||||||
|
[Read the README](https://github.com/rubenwardy/minetest_modding_book/blob/master/README.md).
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user