MTSR/minetest_modding_book
4
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Add README.html and delete unused layout template

Browse Source
This commit is contained in:
rubenwardy 2015-02-16 17:29:05 +00:00
parent bb1cc7e406
commit 02cc4ee2f1
3 changed files with 141 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

252
README.md
View File

@ -1,47 +1,65 @@
Minetest Doc ---
============ title: README for Contributors
layout: default
---
This online book will teach you how to create mods in easy chapters. ## Welcome!
The chapters will explain a concept, give examples, and set tasks for you to complete.
This documentation was created by the Minetest community in order to This project uses Jekyll to turn Markdown into HTML, but you don't need to
help new modders gain a foothold. 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
You can contribute to this project on GitHub. or my email address (see my github profile).
It uses Jekyll to turn Markdown into a website.
Book written by rubenwardy and contributers.
License: CC-BY-SA 3.0
Contributing
------------
You don't need to run jekyll, you can just edit and create files in
chapters. In fact, you don't even need to do markdown, send me a word document
and I can convert it into the correct formatting.
It is the writing which is the hard bit, not the formatting. It is the writing which is the hard bit, not the formatting.
Running as a Website Book written by rubenwardy.
-------------------- License: CC-BY-SA 3.0
You can build it as a website using jekyll. ## Why is this a GitHub repo, rather than a wiki?
**Serving on http://localhost:4000/minetest_doc/** I want to be able to review any changes to make sure that they
fit my idea of quality.
``` ## Finding your way around
$ jekyll serve -b /minetest_doc
```
**Building to folder** * _data/ - Contains the navigation bar file.
(a list of links and link text for the navbar.)
* _includes/ - Contains HTML templates.
* _layouts/ - You can safely ignore this.
* static/ - CSS, images, scripts.
* chapters/ - Markdown files for each chapter.
``` ## Using Jeykll
$ jekyll build
``` I use [Jekyll](http://jekyllrb.com/) 2.5.3
# For Linux based:
$ sudo apt-get install ruby-dev
$ gem install jekyll
$ gem install jekyll-sitemap
# You may need to use sudo on the above commands
### Building as a website
You can build it as a website using [Jekyll](http://jekyllrb.com/)
$ jekyll build
Goes to _site/ Goes to _site/
Commits ### 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"
## Commits
If you are editing or creating a particular chapter, then use commit messages like this: If you are editing or creating a particular chapter, then use commit messages like this:
@ -52,112 +70,120 @@ Entities - created chapter
Just use a normal style commit message otherwise. Just use a normal style commit message otherwise.
HTML and CSS ## Making a Chapter
------------
The HTML is in _includes/. To create a new chapter, make a new file in chapters/.
header.html contains all the HTML code above a chapter's content, Name it something that explains what the chapter is about.
footer.html contains all the HTML code below a chapter's content. Replace spaces with underscores ( _ )
The CSS is in static/
Example Chapter **Template**
---------------
chapters are to be saved to chapters/ {% raw %}
```Markdown ---
--- title: Player Physics
title: Chapter Title layout: default
layout: default root: ../
root: ../ ---
---
Introduction Introduction
------------ ------------
Explain what this chapter will cover. Write an paragraph or so explaining what will be covered in this chapter.
You may use multiple paragraphs, but keep it fairly consise. Explain why/how these concepts are useful in modding
### What you will need: * List the
* List tools you need to complete this chapter * Parts in
* This chapter
### Contents Section
* List -------
* The
* Sections
Section Explaining the concept of something.
-------
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.
You can link to other chapters like this: [chapter title]({{ relative }}/chaptertitle/).// Mod Name
Do it like wikipedia, link words in a sentence but don't explicitly tell the user to view it// - init.lua - the main scripting code file, which is run when the game loads.
or click the link - (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
### Mod Folder Structure Code snippets are tabbed one level in, except for lua snippets, which use a code highligter.
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
---------
Section 2 Explaining another concept
---------
Explaining another concept {% highlight lua %}
print("This file will be run at load time!")
### Mod Pack Folder Structure minetest.register_node("mymod:node",{
Mod Name description = "This is a node",
- modone/ tiles = {
- modtwo/ "mymod_node.png",
- modthree/ "mymod_node.png",
- modfour/ "mymod_node.png",
- Modpack.txt – signals that this is a mod pack, content does not matter "mymod_node.png",
"mymod_node.png",
"mymod_node.png"
},
groups = {cracky = 1}
})
{% endhighlight %}
Example Time Use the highlight tags to highlight Lua code.
------------
You should include a examples. Section 3
---------
### Mod Folder You should include plenty of examples. Each example should
mymod/ be able to be installed in a mod and used. Don't do the thing where
- init.lua you make the reading create the mod line-by-line, it is rather annoying
- depends.txt 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
### depends.txt default
default
### init.lua {% highlight lua %}
{% highlight lua %} print("This file will be run at load time!")
print("This file will be run at load time!")
minetest.register_node("mymod:node",{ minetest.register_node("mymod:node",{
description = "This is a node", description = "This is a node",
tiles = { tiles = {
"mymod_node.png", "mymod_node.png",
"mymod_node.png", "mymod_node.png",
"mymod_node.png", "mymod_node.png",
"mymod_node.png", "mymod_node.png",
"mymod_node.png", "mymod_node.png",
"mymod_node.png" "mymod_node.png"
}, },
groups = {cracky = 1} groups = {cracky = 1}
}) })
{% endhighlight %} {% endhighlight %}
Explain the code here, but their is no need to explain every single line Explain the code here, but there is no need to explain every single line.
Use comments and indentation well.
Tasks Your Turn
----- ---------
* Set some tasks for the user to do * **Set Tasks:** Make tasks for the reader to do.
* Start with easier ones, and work up to harder ones. * **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 understandably.

3
_layouts/index.html
View File

@ -1,3 +0,0 @@
{% include header.html %}
{{ content }}
{% include footer.html %}

3
index.md
View File

@ -29,7 +29,8 @@ Start reading. Use the navigation bar on the left to open a chapter.
Contribution Contribution
------------ ------------
You can contribute to this project on [GitHub](https://github.com/rubenwardy/minetest_modding_book). You can contribute to this project on [GitHub](https://github.com/rubenwardy/minetest_modding_book).\\
Read the [contribution README](README.html).
Written by rubenwardy.\\ Written by rubenwardy.\\
License: [CC-BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/) License: [CC-BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/)