diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 203415486c..27a170f405 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,110 +1,3 @@ # Documentation Contribution Guidelines -First of all, thank you for your interest in contributing to Rocket.Chat Docs. -If this is the first Open Source project you will contribute to, -we strongly suggest reading GitHub's excellent guide -["Contributing to Open Source"](https://guides.github.com/activities/contributing-to-open-source/). - -## Finding something to work on - -When looking for something to work on, you have two options: - -### 1. The Documentation Map - -You can find a map of all the files on the documentation [here](../documentation-map). There you can find what articles are missing or incomplete. This page was created so is easier for the Rocket.Chat team and the community to know the status of the documentation and what they can do to improve it. - -Missing articles will be marked as red - -Incomplete articles will be marked as orange - -All missing/incomplete articles are links to a list with the description of each article marked on the documentation map (you can find this list [here](../missing-and-outdated-list)) - -### 2. Issues - -You can find a list of issues [here](https://github.com/RocketChat/Rocket.Chat.Docs/issues). -When you find something you would like to work on just comment on it and we will add an __In Progress__ label. - -- - - - -## Creating a new Pull Request - -### Requirements - -When you create a new pull request, we expect some requirements to be met. - -- Whenever you add a new article or complete a incomplete article, please update the [Documentation Map](../contributing/documentation/documentation-map) and remove the topic from the [Missing/Incomplete Article List](../contributing/documentation/missing-and-outdated-list) (if necessary). -- If a file is created or moved, you need to update the Table of Contents (You can find the file [here](https://github.com/RocketChat/docs/blob/master/_data/toc.yml)). -- Follow this naming convention for Pull Requests: - - When adding new documentation, add `New Documentation:` before the title. E.g. `New Documentation: Authentication Guide`. - - When fixing documentation, add `Fix Documentation:` before the title. E.g. `Fix Documentation: Authentication Guide`. - - When updating documentation, add `Update Documentation:` before the title. E.g. `Update Documentation: Authentication Guide`. -- For each pull request made, we run tests to check if there are any broken links. You can find how to run these tests locally [here](#test). -- We also use a linter tool to check if the style of the markdown matches our [styleguide](../markdown-styleguide). Here is a link to the [Markdown Linter Tool](https://github.com/markdownlint/markdownlint). - -### Recommended Workflow - -When making small changes like typos and such, there is no problem to edit the file directly on GitHub, but if you are making bigger changes or adding new files to the docs, we recommend following this workflow - -- install ruby (version 2.5 or higher recommended, if using any version prior to 2.5 you will need to install bundler with `gem install bundler`). -- Install the [Markdown Linter Tool](https://github.com/markdownlint/markdownlint) with `gem install mdl`. -- Fork the appropriate repository to your account. -- This is usually [here](https://github.com/RocketChat/docs). -- Clone your fork. -- Run `bundle install`. -- Start the server with `bundle exec "jekyll serve --incremental --safe"`. -- Before starting read our [Markdown Style Guide](../markdown-styleguide). -- Make your changes locally. -- Run the markdown linter tool with `mdl .` on the root directory of the project. -- Run `bundle exec "rake check_links"` with the server running to check for broken links. -- Commit your changes to a new branch. -- Push that branch to your repository. -- Open a PR. -- Make sure you include a description of why you're making the changes. - -### Table of Contents - -Every time you add a new file to the documentation, you will have to add it to the table of contents. - -The table of contents is the left navigation sidebar, and it is the way others will find your new article. - -You can find the table of contents `.yml` file [here](https://github.com/RocketChat/docs/blob/master/_data/toc.yml). - -You have to note that the name you put on the table of content will be _slugfied_, and these names will be used to search for that file. - -E.g. - -If you add a page called `Testing Rocket.Chat Apps`, it will be converted to `testing-rocketchat-apps`, so you will have to name your file `testing-rocketchat-apps.md` - -All words will be lowercased, spaces will be replaced with a `-` and any special character will be removed (like the `.` on `Rocket.Chat`) - -- - - - -## Reporting Issues and Missing Articles - -When you find a problem on the documentation and want to report it to us you have some alternatives: - -### Documentation Map - -If you find that a document either is missing from the docs or is incomplete or outdated, we would recommend that you create a Pull Request adding the missing/incomplete document to the [Documentation Map](../contributing/documentation/documentation-map). - -To add a document to the documentation map you can simply add a new item to the tree map in [here](../contributing/documentation/documentation-map). - -For a missing document you should add - -```HTML -[NAME OF YOUR DOCUMENTATION](../missing-and-outdated-list/#TITLE ON THE MISSING LIST) -``` - -For a incomplete document you should add - -```HTML -[NAME OF YOUR DOCUMENTATION](../missing-and-outdated-list/#TITLE ON THE MISSING LIST) -``` - -After that you will have to write an explanation of how this document should be, or what is the problem with it on the [Missing our Outdated Docs](../missing-and-outdated-list) and link this topic after the `#` on the link you just added to the Documentation Map. - -_Incomplete articles are the ones that are missing a big part of information in them, so if a article is missing a little bit of information, it shouldn't be added to the incomplete list_ - -_Bugs, typos, markdown syntax and such should not be listed on this map_ - -We understand that not everyone has the time to create Pull Requests so feel free to create regular issues too. \ No newline at end of file +You can find the documentation guidelines in [here](contributing/documentation) \ No newline at end of file diff --git a/README.md b/README.md index 23f61e9453..9693ddb49a 100644 --- a/README.md +++ b/README.md @@ -5,18 +5,14 @@ permalink: /index.html # Rocket.Chat Docs -## What would you like to do? +This is the official repository for Rocket.Chat Documentation. -- [Learn how to use Rocket.Chat](user-guides/) -- [Get support](getting-support/) -- [Install Rocket.Chat](installation/) -- [Administer your installation](administrator-guides/) -- [Contribute to the project](contributing/) +## How to run Rocket.Chat Docs locally: -![image](mockup.png) +This is a quick guide on how to run the docs site locally, for a more in depth guide please look [here]( contributing/documentation) -## What is Rocket.Chat? - -Rocket.Chat is a Web Chat Server, developed in JavaScript, using the [Meteor](https://www.meteor.com/install) fullstack framework. - -It is a great solution for communities and companies wanting to privately host their own chat service or for developers looking forward to build and evolve their own chat platforms. +- install ruby (version 2.5 or higher recommended, if using any version prior to 2.5 you will need to install bundler with `gem install bundler`). +- Fork the [repository](https://github.com/RocketChat/docs). +- Clone your fork. +- Run `bundle install` inside of the cloned docs folder. +- Start the server with `bundle exec "jekyll serve --incremental --safe"`. diff --git a/contributing/documentation/contribution-guidelines/README.md b/contributing/documentation/contribution-guidelines/README.md index 69476afbdf..c3002e38e6 100644 --- a/contributing/documentation/contribution-guidelines/README.md +++ b/contributing/documentation/contribution-guidelines/README.md @@ -51,7 +51,7 @@ When making small changes like typos and such, there is no problem to edit the f - Fork the appropriate repository to your account. - This is usually [here](https://github.com/RocketChat/docs). - Clone your fork. -- Run `bundle install`. +- Run `bundle install` inside of the cloned docs folder. - Start the server with `bundle exec "jekyll serve --incremental --safe"`. - Before starting read our [Markdown Style Guide](../markdown-styleguide). - Make your changes locally. diff --git a/find-broken-links.js b/find-broken-links.js deleted file mode 100644 index d6abecfb65..0000000000 --- a/find-broken-links.js +++ /dev/null @@ -1,73 +0,0 @@ -// List all files in a directory in Node.js recursively in a synchronous fashion -var fs = require('fs'); -var path = require('path'); - - function walkSync(dir, cbFile) { - files = fs.readdirSync(dir); - - files.forEach(function(file) { - file = path.join(dir, file); - if (fs.statSync(file).isDirectory()) { - walkSync(file, cbFile); - } else { - cbFile(file); - } - }); -}; - -walkSync(__dirname, function(file) { - if (/\.md$/.test(file) === false) { - return; - } - - var text = fs.readFileSync(file).toString(); - - var links = []; - - // text.replace(/\[(.*?)\]\((.*?)\)/gm, function(link, text, url) { - // if (/^https?:\/\/.+/.test(url)) { - // // TODO - // } else if (/mailto:.+/.test(url)) { - // // TODO - // } else if (/#.+/.test(url)) { - // // TODO - // } else { - // // console.log(url); - // url = decodeURIComponent(url); - // if (/^\//.test(url)) { - // var link2 = path.join(__dirname, url) - // } else { - // var link2 = path.join(path.dirname(file), url) - // } - // try { - // fs.statSync(link2) - // } catch (error) { - // links.push(url); - // } - // } - // }) - - text.replace(/\[(\d+)\]:(.+)/gm, function(link, text, url) { - // [3]:../13.%20Update%20Message - // console.log(url); - url = decodeURIComponent(url); - if (/^\//.test(url)) { - var link2 = path.join(__dirname, url) - } else { - var link2 = path.join(path.dirname(file), url) - } - try { - fs.statSync(link2) - } catch (error) { - links.push(url); - } - }); - - if (links.length) { - console.log(file); - links.forEach(function(link) { - console.log(' ', link); - }); - console.log(); - } -}); diff --git a/markdown-styleguide.md b/markdown-styleguide.md deleted file mode 100644 index f534e21bd6..0000000000 --- a/markdown-styleguide.md +++ /dev/null @@ -1,481 +0,0 @@ -# Markdown Style Guide - -The Rocket.Chat documentation supports the [Markdown Markup Language](https://en.wikipedia.org/wiki/Markdown) (You can also find a "Cheatsheet" [here](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)) - -Markdown can be written in various different styles, in this document you will find the standard formatting guide for creating Rocket.Chat documentation. - -We are currently running a markdown [linter](https://github.com/markdownlint/markdownlint) on incoming Pull Requests, so it is a good idea to download it and run it locally before submitting a Pull Request. - -All the rules listed here have their respective code attached here, so if the linter fails you can come here and check out the rule that was broken. - -You can run the Markdown linter locally by installing this [Markdown Linter Tool](https://github.com/markdownlint/markdownlint) -and running the command `mdl ../` command on the docs main folder. - -## Rules - -### MD001 - Header levels should only increment by one level at a time - -Headers should not be skipped, instead incremented one by one - -**Wrong**: - - # Header 1 - - ### Header 3 - - We skipped out a 2nd level header in this document - -**Correct**: - - # Header 1 - - ## Header 2 - - ### Header 3 - - #### Header 4 - - ## Another Header 2 - - ### Another Header 3 - -### MD002 - First header should be a top level header - -The first header of the document should be a top level header (H1). - -**Wrong**: - - ## This isn't a H1 header - - ### Another header - -**Correct**: - - # Start with a H1 header - - ## Then use a H2 for subsections - -### MD003 - Header style - -The header style used on documents should be `atx`. - -**Wrong**: - - Setext style H1 - =============== - - Setext style H2 - --------------- - - ### ATX style H3 - -**Correct**: - - # ATX style H1 - - ## ATX style H2 - -### MD004 - Unordered list style - -Lists should be created using dashes. - -**Wrong**: - - * Item 1 - + Item 2 - - Item 3 - -**Correct**: - - - Item 1 - - Item 2 - - Item 3 - -### MD005 - No inconsistent indentation for list items at the same level - -Lists should have consistent indentation, usually this rule will be triggered because of a typo. - -**Wrong**: - - - Item 1 - - Nested Item 1 - - Nested Item 2 - - A misaligned item - -**Correct**: - - - Item 1 - - Nested Item 1 - - Nested Item 2 - - Nested Item 3 - -### MD006 - Consider starting bulleted lists at the beginning of the line - -Bulleted lists should start on the beginning of the line. - -**Wrong**: - - Some text - - * List item - * List item - -**Correct**: - - Some test - - * List item - * List item - -### MD007 - Unordered list indentation - -List items should be indented using 4 spaces. - -**Wrong**: - - * List item - * Nested list item indented by 3 spaces - -**Correct**: - - * List item - * Nested list item indented by 4 spaces - -### MD009 - No trailing spaces - -There shouldn't have any trailing spaces after the end of the lines. - -To fix this, find the line that is triggered and remove any trailing spaces from the end. - -### MD010 - No hard tabs - -Spaces should be used for indentation instead of hard tabs. - -To fix this, replace any hard tab characters with spaces instead. - -### MD011 - No reversed link syntax - -When creating links you should use the `[]` surrounding the text and `()` surrounding the link. - -**Wrong**: - - (Incorrect link syntax)[http://www.example.com/] - -**Correct**: - - [Correct link syntax](http://www.example.com/) - -### MD012 - No multiple consecutive blank lines - -There should not have more than one consecutive blank line on the document. - -**Wrong**: - - Some text here - - - Some more text here - -**Correct**: - - Some text here - - Some more text here - -### MD018 - Use space after hash on atx style header - -There should be a space after the hashes on atx style headers. - -**Wrong**: - - #Header 1 - - ##Header 2 - -**Correct**: - - # Header 1 - - ## Header 2 - -### MD019 - No multiple spaces after hash on atx style header - -There shouldn't have more than 1 space after the hash on atx style headers. - -**Wrong**: - - # Header 1 - - ## Header 2 - -**Correct**: - - # Header 1 - - ## Header 2 - -### MD022 - Headers should be surrounded by blank lines - -All headers should have a blank line both before and after (except where the header is at the beginning or end of the document) - -**Wrong**: - - # Header 1 - Some text - - Some more text - ## Header 2 - -**Correct**: - - # Header 1 - - Some text - - Some more text - - ## Header 2 - -### MD023 - Headers must start at the beginning of the line - -**Wrong**: - - Some text - - # Indented header - -**Correct**: - - Some text - - # Header - -### MD025 - No multiple top level headers in the same document - -There should only have one top level header (`h1`) on a document. - -**Wrong**: - - # Top level header - - # Another top level header - -**Correct**: - - # Title - - ## Header - - ## Another header - -### MD027 - No multiple spaces after blockquote symbol - -Blockquote should not have more than one space after the blockquote symbol ( `>` ). - -**Wrong**: - - > This is a block quote with bad indentation - > there should only be one. - -**Correct**: - - > This is a block quote with bad indentation - > there should only be one. - -### MD028 - No blank line inside blockquote - -There shouldn't have a blank line inside the same blockquote. - -**Wrong**: - - > This is a blockquote - > which is immediately followed by - - > this blockquote. Unfortunately - > In some parsers, these are treated as the same blockquote. - -**Correct**: - - > This is a blockquote. - - And Jimmy also said: - - > This too is a blockquote. - -Alternatively, if they are supposed to be the same quote, then add the blockquote symbol at the beginning of the blank line - - > This is a blockquote. - > - > This is the same blockquote. - -### MD029 - Ordered list item prefix - -Ordered lists should be ordered by a prefix that increases in numerical order. - -**Wrong**: - - 1. Do this. - 1. Do that. - 1. Done. - -**Correct**: - - 1. Do this. - 2. Do that. - 3. Done. - -### MD030 - Space after list markers - -There should be only one space after a list marker. - -**Wrong**: - - *Foo - *Bar - *Baz - - 1. Foo - 1. Bar - 1. Baz - -**Correct**: - - * Foo - * Bar - * Baz - - 1. Foo - 1. Bar - 1. Baz - - 1. Foo - * Bar - 1. Baz - -### MD031 - Fenced code blocks should be surrounded by blank lines - -Fenced code blocks should be surrounded by blank lines. - -**Wrong**: - - Some text - `` ` - Code block - `` ` - - `` ` - Another code block - `` ` - Some more text - -**Correct**: - - Some text - - ``` - Code block - ``` - - ``` - Another code block - ``` - - Some more text - -### MD032 - Lists should be surrounded by blank lines - -Lists should be surrounded by blank lines. - -**Wrong**: - - Some text - * Some - * List - - 1. Some - 2. List - Some text - -**Correct**: - - Some text - - * Some - * List - - 1. Some - 2. List - - Some text - -### MD034 - No bare URLs - -There should no bare urls on the document, surround the links with angle brackets (`< >`). - -**Wrong**: - - For more information, see http://www.example.com/. - -**Correct**: - - For more information, see . - -### MD035 - Horizontal rule style - -Horizontal rules should be created using three slashes (`---`). - -**Wrong**: - - *** - - * * * - - **** - -**Correct**: - - --- - -### MD037 - No spaces inside emphasis markers - -There shouldn't have spaces inside emphasis markers (bold, italic). - -**Wrong**: - - Here is some ** bold ** text. - - Here is some _ italic _ text. - -**Correct**: - - Here is some **bold** text. - - Here is some _italic_ text. - -### MD038 - No spaces inside code span elements - -There shouldn't have spaces inside code span elements. - -**Wrong**: - - ` some text ` - - `some text ` - - ` some text` - -**Correct**: - - `some text` - -### MD039 - No spaces inside link text - -There shouldn't have spaces inside link texts. - -**Wrong**: - - [ a link ](http://www.example.com/) - -**Correct**: - - [a link](http://www.example.com/) diff --git a/mockup.png b/mockup.png deleted file mode 100644 index ee462560fc..0000000000 Binary files a/mockup.png and /dev/null differ diff --git a/redirects.json b/redirects.json deleted file mode 100644 index b59b5580ef..0000000000 --- a/redirects.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "/developer-guides/rest-api/offset-and-count-info": "/docs/developer-guides/rest-api/offset-and-count-and-sort-info" -}