Add README.html and delete unused layout template
This commit is contained in:
rubenwardy
parent
bb1cc7e406
commit
02cc4ee2f1
192
README.md
192
README.md
@ -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.
|
||||
The chapters will explain a concept, give examples, and set tasks for you to complete.
|
||||
## Welcome!
|
||||
|
||||
This documentation was created by the Minetest community in order to
|
||||
help new modders gain a foothold.
|
||||
|
||||
You can contribute to this project on GitHub.
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
```
|
||||
$ jekyll serve -b /minetest_doc
|
||||
```
|
||||
## Finding your way around
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
@ -52,22 +70,18 @@ Entities - created chapter
|
||||
|
||||
Just use a normal style commit message otherwise.
|
||||
|
||||
HTML and CSS
|
||||
------------
|
||||
## Making a Chapter
|
||||
|
||||
The HTML is in _includes/.
|
||||
header.html contains all the HTML code above a chapter's content,
|
||||
footer.html contains all the HTML code below a chapter's content.
|
||||
The CSS is in static/
|
||||
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 ( _ )
|
||||
|
||||
Example Chapter
|
||||
---------------
|
||||
**Template**
|
||||
|
||||
chapters are to be saved to chapters/
|
||||
{% raw %}
|
||||
|
||||
```Markdown
|
||||
---
|
||||
title: Chapter Title
|
||||
title: Player Physics
|
||||
layout: default
|
||||
root: ../
|
||||
---
|
||||
@ -75,16 +89,12 @@ root: ../
|
||||
Introduction
|
||||
------------
|
||||
|
||||
Explain what this chapter will cover.
|
||||
You may use multiple paragraphs, but keep it fairly consise.
|
||||
Write an paragraph or so explaining what will be covered in this chapter.
|
||||
Explain why/how these concepts are useful in modding
|
||||
|
||||
### What you will need:
|
||||
* List tools you need to complete this chapter
|
||||
|
||||
### Contents
|
||||
* List
|
||||
* The
|
||||
* Sections
|
||||
* List the
|
||||
* Parts in
|
||||
* This chapter
|
||||
|
||||
Section
|
||||
-------
|
||||
@ -92,10 +102,9 @@ 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 don't explicitly tell the user to view it//
|
||||
or click the link
|
||||
Do it like Wikipedia, link words in a sentence but avoid explicitly telling the user to view it//
|
||||
or click the link.
|
||||
|
||||
### Mod Folder Structure
|
||||
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.
|
||||
@ -111,29 +120,6 @@ Section 2
|
||||
|
||||
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 %}
|
||||
print("This file will be run at load time!")
|
||||
|
||||
@ -151,13 +137,53 @@ minetest.register_node("mymod:node",{
|
||||
})
|
||||
{% 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
|
||||
* Start with easier ones, and work up to harder ones.
|
||||
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 understandably.
|
||||
|
||||
@ -1,3 +0,0 @@
|
||||
{% include header.html %}
|
||||
{{ content }}
|
||||
{% include footer.html %}
|
||||
3
index.md
3
index.md
@ -29,7 +29,8 @@ Start reading. Use the navigation bar on the left to open a chapter.
|
||||
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.\\
|
||||
License: [CC-BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user