gistfile1.txt
| # README-README: A Style Guide for README files |
| ## Contents |
| The `README.md` file and supporting documents should describe the following, in this order. If the file starts getting long, break it into pieces |
| * **Project Titles** as a level-1 heading |
| - with descriptive tagline: I should be informed and intrigued. Examples: |
| - 'Sinatra is a DSL for quickly creating web applications in Ruby with minimal |
| effort' |
| - 'Rails is a web-application framework that includes everything needed to create |
| database-backed web applications according to the Model-View-Controller (MVC) pattern.' |
| - 'Resque (pronounced like 'rescue') is a Redis-backed library for creating |
| background jobs, placing those jobs on multiple queues, and processing |
| them later.' |
| * **Overview** |
| - what it does |
| - why you might want to use it, and why you might not |
| * **Example Usage**: a basic example. Nothing fancy -- put rich examples in the detailed usage section |
| * **Getting Started** |
| - installation & prerequisites |
| - how to run examples and tests |
| - include a `Procfile` to start any necessary servers or daemon processes |
| - location of: |
| - code |
| - issue tracker |
| - wiki |
| - blog posts, screencasts, etc |
| - compiled documentation (add the project to [rdoc.info](http://rdoc.info)) |
| - travis-ci results |
| - mailing list |
| * **Design Goals** |
| - lightweight or full-featured? |
| - performance, flexibility, expressiveness? |
| * **Detailed Usage** |
| - models and interface |
| - examples |
| - configuration |
| - middleware or plugins |
| - how it works |
| * **Comparable Tools** |
| * **Developer info** |
| - Important Components |
| - layout of internal code tree |
| - Limitations and known issues |
| - performance and benchmarking |
| * **Colophon** |
| - Credits -- everyone who has contributed code, libraries from which we've borrowed code. |
| - Copyright and License -- state the license type (typically 'Apache 2.0' or 'All Rights Reserved and Confidential') and refer to the `LICENSE.md` file. Don't paste the license contents in here. |
| - How to contribute |
| - References |
| ## Formatting |
| * Call the file `README.md`. |
| * Write in markdown format. |
| - You should use triple backtick blocks for code, and supply a language prefix: |
| ```ruby |
| def hello(str) |
| puts 'hello #{str}!' |
| end |
| ``` |
| * Do not wrap lines. In emacs, enable the `longlines-mode` to make your document word wrap intelligently. |
| ## Supporting Documentation |
| Besides a `README.md`, your repo should contain a `CHANGELOG.md` summarizing major code changes, a `LICENSE.md` describing the code's license (typically Apache 2.0 for our open-source projects, All Rights Reserved for internal projects), and a `notes/` directory that is a git submodule of the project's wiki. See the [style guide for repo organization](https://github.com/infochimps-labs/style_guide/blob/master/style-guide-for-repo-organization.md) for more details. |
- Create a home page auto-magically from README.md If you are a GitHub user named%username% and and create a repository at%username%.github.io and add a README.md file, then the README file will be auto-magically be translated into HTML and will display as HTML when you go to This README is a good example.
- This GitHub organization and repository has a single, simple mission: to help you create better, more useful README files for use in GitHub and elsewhere Viewing this file View this file as source code.
Github Readme Format Code
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment
Github Format Readme
Creating your README When you create a new repository though GitHub, select “Initialize this repository with a README” unless you plan to import an existing repository. Your README.md file is now available for editing in your brand-new repository. You can tell GitHub to ignore (or escape) Markdown formatting by using before the Markdown character. Let's rename.our-new-project. to.our-old-project. For more information, see Daring Fireball's 'Markdown Syntax.' Further reading. GitHub Flavored Markdown Spec 'About writing and formatting on GitHub' 'Working with advanced formatting'. Even though GitHub Readme files (typically./readme.md) are Markdown, and although Markdown supports HTML, you can’t put.