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

192
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
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 $ 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,22 +70,18 @@ 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: Chapter Title title: Player Physics
layout: default layout: default
root: ../ root: ../
--- ---
@ -75,16 +89,12 @@ 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
* List
* The
* Sections
Section Section
------- -------
@ -92,10 +102,9 @@ Section
Explaining the concept of something. Explaining the concept of something.
You can link to other chapters like this: [chapter title]({{ relative }}/chaptertitle/).// You can link to other chapters like this: [chapter title]({{ relative }}/chaptertitle/).//
Do it like wikipedia, link words in a sentence but don't explicitly tell the user to view it// Do it like Wikipedia, link words in a sentence but avoid explicitly telling the user to view it//
or click the link or click the link.
### Mod Folder Structure
Mod Name Mod Name
- init.lua - the main scripting code file, which is run when the game loads. - 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) depends.txt - a list of mod names that needs to be loaded before this mod.
@ -111,29 +120,6 @@ Section 2
Explaining another concept Explaining another concept
### Mod Pack Folder Structure
Mod Name
- modone/
- modtwo/
- modthree/
- modfour/
- Modpack.txt – signals that this is a mod pack, content does not matter
Example Time
------------
You should include a examples.
### Mod Folder
mymod/
- init.lua
- depends.txt
### depends.txt
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!")
@ -151,13 +137,53 @@ minetest.register_node("mymod:node",{
}) })
{% endhighlight %} {% endhighlight %}
Explain the code here, but their is no need to explain every single line Use the highlight tags to highlight Lua code.
Tasks Section 3
----- ---------
* Set some tasks for the user to do You should include plenty of examples. Each example should
* Start with easier ones, and work up to harder ones. 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 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/)