From 02cc4ee2f17b276d89b1afd5aaf61661fbf450d1 Mon Sep 17 00:00:00 2001 From: rubenwardy Date: Mon, 16 Feb 2015 17:29:05 +0000 Subject: [PATCH] Add README.html and delete unused layout template --- README.md | 252 ++++++++++++++++++++++++-------------------- _layouts/index.html | 3 - index.md | 3 +- 3 files changed, 141 insertions(+), 117 deletions(-) delete mode 100644 _layouts/index.html diff --git a/README.md b/README.md index 57b1077..c465df6 100644 --- a/README.md +++ b/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. -``` -$ jekyll build -``` +## 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 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,112 +70,120 @@ 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 -layout: default -root: ../ ---- + --- + title: Player Physics + layout: default + root: ../ + --- -Introduction ------------- + 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 + * List the + * Parts in + * This chapter -### Contents -* List -* The -* Sections + Section + ------- -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/).// -Do it like wikipedia, link words in a sentence but don't explicitly tell 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 -### 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. - - (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. -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 - Mod Name - - modone/ - - modtwo/ - - modthree/ - - modfour/ - - Modpack.txt – signals that this is a mod pack, content does not matter + 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 %} -Example Time ------------- + Use the highlight tags to highlight Lua code. -You should include a examples. + Section 3 + --------- -### Mod Folder - mymod/ - - init.lua - - depends.txt + 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 -### depends.txt - default + default -### init.lua -{% highlight lua %} -print("This file will be run at load time!") + {% 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 %} + 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 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 -* Start with easier ones, and work up to harder ones. + * **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. diff --git a/_layouts/index.html b/_layouts/index.html deleted file mode 100644 index 4f0db4c..0000000 --- a/_layouts/index.html +++ /dev/null @@ -1,3 +0,0 @@ -{% include header.html %} -{{ content }} -{% include footer.html %} diff --git a/index.md b/index.md index 8c503f1..4ba9bda 100644 --- a/index.md +++ b/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/)