learnxinyminutes-docs/CONTRIBUTING.md

113 lines
3.9 KiB
Markdown
Raw Normal View History

2015-10-23 18:25:42 +00:00
# Contributing
2016-02-15 22:47:35 +00:00
All contributions are welcome, from the tiniest typo to a brand new article.
Translations in all languages are welcome (or, for that matter, original
articles in any language). Send a pull request or open an issue any time of day
or night.
2015-10-23 18:25:42 +00:00
2016-02-15 22:47:35 +00:00
**Please prepend the tag `[language/lang-code]` to your issues and pull
requests.** For example, `[python/en]` for English Python. This will help
everyone pick out things they care about.
2015-10-23 18:25:42 +00:00
2016-02-15 22:47:35 +00:00
We're happy for any contribution in any form, but if you're making more than one
major change (i.e. translations for two different languages) it would be super
cool of you to make a separate pull request for each one so that someone can
review them more effectively and/or individually.
2015-10-23 18:25:42 +00:00
## Style Guidelines
* **Keep lines under 80 chars**
2024-12-09 10:38:02 +00:00
* Try to keep line length in code blocks to 80 characters or fewer.
* Otherwise, the text will overflow and look odd.
* This and other potential pitfalls to format the content consistently are
2024-12-09 10:38:02 +00:00
identified by [markdownlint](https://github.com/markdownlint/markdownlint).
* **Prefer example to exposition**
* Try to use as few words as possible.
* Code examples are preferred over exposition in all cases.
* **Eschew surplusage**
* We welcome newcomers, but the target audience for this site is programmers
with some experience.
* Try to avoid explaining basic concepts except for those specific to the
language in question.
* Keep articles succinct and scannable. We all know how to use Google here.
* **Use UTF-8**
* For translations (or EN articles with non-ASCII characters) please ensure
your file is UTF-8 encoded.
2024-04-03 11:16:08 +00:00
* Leave out the byte-order-mark (BOM) at the start of the file (in Vim, use
`:set nobomb`).
* You can check if the file contains a BOM on Linux/Unix systems by running
`file language.html.markdown` You will see this if it uses a BOM:
`UTF-8 Unicode (with BOM) text`.
2015-10-23 18:25:42 +00:00
2016-02-15 22:47:35 +00:00
### Header configuration
2015-10-23 18:25:42 +00:00
2016-02-15 22:47:35 +00:00
The actual site uses Middleman to generate HTML files from these Markdown ones.
Middleman, or at least the custom scripts underpinning the site, requires that
some key information be defined in the header.
2015-10-23 18:25:42 +00:00
2016-02-15 22:47:35 +00:00
The following fields are necessary for English articles about programming
languages:
* **language** The *programming language* in question
* **contributors** A list of [author, URL] lists to credit
2015-10-23 18:25:42 +00:00
Other fields:
* **category**: The category of the article. So far, can be one of *language*,
*tool* or *Algorithms & Data Structures*. Defaults to *language* if omitted.
* **filename**: The filename for this article's code. It will be fetched, mashed
2016-02-15 22:47:35 +00:00
together, and made downloadable.
2024-12-09 10:38:02 +00:00
* For non-English articles, *filename* will be used from the English article,
unless you want to overwrite it for some reason.
2015-10-23 18:25:42 +00:00
2024-12-09 10:38:02 +00:00
Here's an example header for Ruby:
2015-10-23 18:25:42 +00:00
```yaml
*--
name: Ruby
2024-12-09 10:38:02 +00:00
filename: learnruby.rb
2015-10-23 18:25:42 +00:00
contributors:
- ["Doktor Esperanto", "http://example.com/"]
- ["Someone else", "http://someoneelseswebsite.com/"]
*--
2015-10-23 18:25:42 +00:00
```
2017-11-13 21:45:40 +00:00
2024-04-03 11:16:08 +00:00
### Syntax highlighter
2024-12-09 10:38:02 +00:00
[Pygments](https://pygments.org/languages/) is used for syntax highlighting.
2024-04-03 11:16:08 +00:00
### Should I add myself as a contributor?
2017-11-13 21:45:40 +00:00
If you want to add yourself to contributors, keep in mind that contributors get
equal billing, and the first contributor usually wrote the whole article. Please
use your judgment when deciding if your contribution constitutes a substantial
2017-11-13 21:45:40 +00:00
addition or not.
## Building the site locally
2024-12-09 10:38:02 +00:00
Install Python. On macOS this can be done with [Homebrew](https://brew.sh/).
2024-10-30 05:29:13 +00:00
```sh
2024-12-09 10:38:02 +00:00
brew install python
2024-10-30 05:29:13 +00:00
```
Then clone two repos, install dependencies and run.
2024-10-30 05:29:13 +00:00
```sh
# Clone website
2024-10-30 05:29:13 +00:00
git clone https://github.com/adambard/learnxinyminutes-site
# Clone docs (this repo) nested in website
2024-10-30 05:29:13 +00:00
git clone https://github.com/<YOUR-USERNAME>/learnxinyminutes-docs ./learnxinyminutes-site/source/docs/
# Install dependencies
2024-10-30 05:29:13 +00:00
cd learnxinyminutes-site
2024-12-09 10:38:02 +00:00
pip install -r requirements.txt
2024-10-30 05:29:13 +00:00
# Run
2024-12-09 10:38:02 +00:00
python build.py
cd build
python -m http.server
# open http://localhost:8000/ in your browser of choice
2024-10-30 05:29:13 +00:00
```