-
Notifications
You must be signed in to change notification settings - Fork 394
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
README/contributing: update after migration to Gatsby (#1138)
* readme/contributing: update after migration to Gatsby * README: fix copyright, include proper links, refactor sections * docs contib guide: update, fix linters a litle bit * contrib: update and improve writing a blog post section * readme/contrib: address PRs review * readme/contrib: address second review
- Loading branch information
1 parent
838c7ee
commit ba75c02
Showing
9 changed files
with
264 additions
and
157 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| public | ||
| .cache |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,119 +3,49 @@ | |
| [](https://codeclimate.com/github/iterative/dvc.org/maintainability) | ||
| [](https://circleci.com/gh/iterative/dvc.org) | ||
|
|
||
| [DVC](https://github.com/iterative/dvc) project documentation and website source | ||
| code. | ||
| [DVC](https://github.com/iterative/dvc) project website's source code. | ||
| [Documentation](https://dvc.org/doc) and [blog](https://dvc.org/blog) content. | ||
| Contributions to are welcome! | ||
|
|
||
| ## Installation | ||
| # Contributing Docs | ||
|
|
||
| Make sure you have the latest LTS version of [Node.js](https://nodejs.org) and | ||
| [Yarn](https://yarnpkg.com) installed. | ||
|
|
||
| Run `yarn`. | ||
|
|
||
| ## Commands | ||
|
|
||
| - `yarn develop` - run dev server with hot reload. | ||
| - `yarn build` - build static assets to `public` folder. | ||
| - `yarn serve` - run static server over the `public` folder content to check | ||
| build results. | ||
| - `yarn lint-ts` - lint `.ts` and `.tsx` for compilance with code style and | ||
| check its for type errors. | ||
| - `yarn lint-css` - lint `.css` files for compilance with code style. | ||
|
|
||
| ## ENV variables | ||
|
|
||
| - `GA_ID` – id of the Google Analytics counter. | ||
| - `ANALYZE` - boolean prop to run webpack-analyzer | ||
| - `SENTRY_DSN` - sentry dsn url for tracking errors | ||
|
|
||
| ## Technologies | ||
|
|
||
| This docs engine was built using [Gatsby.js](https://www.gatsbyjs.org/). | ||
| [Algolia](https://www.algolia.com/products/search/) uses to provide full text | ||
| search. | ||
| Please see our | ||
| [Contributing guide](https://dvc.org/doc/user-guide/contributing/docs) for more | ||
| details. | ||
|
|
||
| Please feel free to use it for your own sites and | ||
| [reach out to us](https://dvc.org/support) if you have any questions. | ||
| [](https://sourcerer.io/fame/shcheklein/iterative/dvc.org/links/0) | ||
| [](https://sourcerer.io/fame/shcheklein/iterative/dvc.org/links/1) | ||
| [](https://sourcerer.io/fame/shcheklein/iterative/dvc.org/links/2) | ||
| [](https://sourcerer.io/fame/shcheklein/iterative/dvc.org/links/3) | ||
| [](https://sourcerer.io/fame/shcheklein/iterative/dvc.org/links/4) | ||
| [](https://sourcerer.io/fame/shcheklein/iterative/dvc.org/links/5) | ||
| [](https://sourcerer.io/fame/shcheklein/iterative/dvc.org/links/6) | ||
| [](https://sourcerer.io/fame/shcheklein/iterative/dvc.org/links/7) | ||
|
|
||
| # Contributing | ||
| # Writing a blog post | ||
|
|
||
| We welcome contributions to the DVC docs by the community! | ||
| Please, [contact us](mailto:[email protected]) if you'd like to write something | ||
| cool together or publish your content on our [blog](https://dvc.org/blog). | ||
|
|
||
| You can refer to our | ||
| [Contributing guide](https://dvc.org/doc/user-guide/contributing/docs) for more | ||
| details. Thank you! | ||
| Please see our | ||
| [Writing a Blog Post guide](https://dvc.org/doc/user-guide/contributing/blog) | ||
| for more details on how to write and submit a new blog post. | ||
|
|
||
| **If you need help:** | ||
| # Getting help | ||
|
|
||
| If you have any questions, please join the [community](https://dvc.org/chat) and | ||
| use the `#dev-docs` channel to discuss any issues in our website or docs. We are | ||
| very responsive and happy to help. | ||
|
|
||
| # Writing blog posts | ||
|
|
||
| Create `.md` file in the `content/blog` folder. File name will be used as | ||
| `slug`. | ||
|
|
||
| Write frontmatter in the following format: | ||
|
|
||
| ```yml | ||
| --- | ||
| title: Hello World | ||
| date: '2015-05-01T22:12:03.284Z' | ||
| description: 'Hello World' | ||
| descriptionLong: | | ||
| Some long | ||
| multiline | ||
| text | ||
| picture: /uploads/image.jpeg | ||
| pictureComment: Some Comment | ||
| author: ../authors/author_name.md | ||
| tags: | ||
| - Open Source | ||
| - Machine Learning | ||
| - Data Science | ||
| - Version Control | ||
| - AI | ||
| --- | ||
|
|
||
| ``` | ||
|
|
||
| - `title` - **Required.** Title of the post. | ||
| - `date` - **Required.** Post date. Will be used to sort posts and in RSS. | ||
| - `description` - **Required.** Short description to show in the feed. | ||
| - `descriptionLong` - Optional long description to show before image on the post | ||
| page. If not set, `description` will be used instead. | ||
| - `picture` - Optional cover image. | ||
| - `pictureComment` - Optional cover image comment. | ||
| - `author` - **Required** Relative path to `.md` file with information about the | ||
| author. | ||
| - `tags` - Optional list of tags. | ||
|
|
||
| ## Adding authors | ||
|
|
||
| Create `.md` file in the `content/authors` folder. | ||
|
|
||
| Write frontmatter in the following format: | ||
|
|
||
| ```yml | ||
| path: ../authors/relative_path_to_file.md | ||
| name: Author's Name | ||
| avatar: /uploads/avatar.jpeg | ||
| ``` | ||
| - `path` - **Required** String that the CMS will insert to the author field in | ||
| the blog post. Should be equal to the path from the blog post to the author's | ||
| `.md` file. | ||
| - `name` – **Required** Author's name. | ||
| - `avatar` - **Required** relative path to the author's avatar. | ||
|
|
||
| # Copyright | ||
|
|
||
| This project is distributed under the Apache license version 2.0 (see the | ||
| LICENSE file in the project root). | ||
| Source code of this project is distributed under the Apache license version 2.0 | ||
| (see the LICENSE file in the project root). | ||
|
|
||
| By submitting a pull request for this project, you agree to license your | ||
| contribution under the Apache license version 2.0 to this project. | ||
| Except where otherwise noted, documentation, blog content, images are licensed | ||
| under a [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) license. | ||
|
|
||
| If you use images, please make a reference to the original site. | ||
| By submitting a pull request for this project, you agree to license your | ||
| contribution under the Apache license 2.0 (source code) or CC BY 4.0 | ||
| (documentation). Exceptions could be made to content and any other materials | ||
| that are published on our [blog](https://dvc.org/blog). | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,145 @@ | ||
| # Writing Blog Posts | ||
|
|
||
| To create a new post, you need to create a PR to the DVC website | ||
| [project](https://github.com/iterative/dvc.org). | ||
|
|
||
| ## Prepare your environment | ||
|
|
||
| Set up the | ||
| [Development environment](/doc/user-guide/contributing/docs#development-environment) | ||
| to see how your content will look like after you publish it. In the | ||
| `yarn develop` mode you will be able to run the website locally, and it'll be | ||
| updating content in your browser as you edit the post. | ||
|
|
||
| ## Add a post | ||
|
|
||
| Create a Markdown file in the `content/blog` folder. File name must follow the | ||
| pattern: `YYYY-MM-DD-my-new-blog-post.md`. After merging this file into the | ||
| `master` branch, blog post will be published at `blog/my-new-blog-post` address | ||
| automatically. | ||
|
|
||
| Write front matter in the following format: | ||
|
|
||
| ```yml | ||
| --- | ||
| title: Hello World | ||
| date: '2015-05-01T22:12:03.284Z' | ||
| description: 'Hello World' | ||
| descriptionLong: | | ||
| Some long | ||
| multiline | ||
| text (supports _basic_ [Markdown](link)) | ||
| picture: /uploads/image.jpeg | ||
| pictureComment: Some _Comment_ (supports _basic_ [Markdown](link)) | ||
| author: ../authors/author_name.md | ||
| tags: | ||
| - Open Source | ||
| - Machine Learning | ||
| - Data Science | ||
| - Version Control | ||
| - AI | ||
| --- | ||
|
|
||
| ``` | ||
|
|
||
| - `title` - **Required.** Title of the post. | ||
| - `date` - **Required.** Publication date in the `YYYY-MM-DD` format. Will be | ||
| used to sort posts and in RSS. | ||
| - `description` - **Required.** Short description to show in the feed. | ||
| - `descriptionLong` - Optional long description to show before the image on the | ||
| post page. If not set, `description` will be used instead. Supports basic | ||
| Markdown markup. | ||
| - `picture` - Optional cover image. | ||
| - `pictureComment` - Optional cover image comment. Supports basic Markdown | ||
| markup. | ||
| - `author` - **Required.** Relative path to `.md` file with information about | ||
| the author. See | ||
| [Adding authors](/doc/user-guide/contributing/blog#adding-authors) to add a | ||
| new author. | ||
| - `commentsUrl` - Optional link to the [DVC forum](https://discuss.dvc.org) | ||
| topic. It will contain comments for the post. | ||
| - `tags` - Optional list of tags. | ||
|
|
||
| ## Content guidelines | ||
|
|
||
| It's recommended to follow all the relevant recommendations from the | ||
| [Doc style guidelines](/doc/user-guide/contributing/docs#doc-style-guidelines-javascript-and-markdown). | ||
|
|
||
| ### Adding images | ||
|
|
||
| > 🙏 Please, be sensible about image size you are about to commit, run some | ||
| > online image optimizer. Huge images pollute Git index, slow down `git clone`, | ||
| > deployment, and other operations with the repository. | ||
| The original image should be 2x height and width of the one you want to see on | ||
| the screen to look sharp. To add images, put them into `static/uploads` and | ||
| reference like this: | ||
|
|
||
| ```md | ||
|  | ||
| ``` | ||
|
|
||
| To add a subtitle: | ||
|
|
||
| ```md | ||
| _subtitle [with a link](link)_ | ||
| ``` | ||
|
|
||
| To set the image size and text wrap: | ||
|
|
||
| ```md | ||
|  | ||
|  | ||
|  | ||
|  | ||
|  | ||
| ``` | ||
|
|
||
| ### Embedding links | ||
|
|
||
| Any URLs | ||
| [supported by `gatsby-remark-embedder`](https://github.com/MichaelDeBoey/gatsby-remark-embedder#supported-services) | ||
| such as Youtube and Twitter share links will be embedded automatically. You just | ||
| need to paste them in the post Markdown, for example: | ||
|
|
||
| ```md | ||
| ... Check out this great video right here: | ||
|
|
||
| https://youtu.be/4h6I9_xeYA4 | ||
|
|
||
| And now lets move onto ... | ||
| ``` | ||
|
|
||
| You can ember a preview of any other website using `<external-link>` tag: | ||
|
|
||
| ```md | ||
| ... Check out this great project: | ||
|
|
||
| <external-link | ||
| href="https://dvc.org/doc" | ||
| title="Open-source tools to version control Machine Learning models and experiments" | ||
| description="AI and ML are becoming an essential part of the engineering..." | ||
| link="dvc.org" | ||
| image="/uploads/images/image.png" /> | ||
|
|
||
| And now lets move onto ... | ||
| ``` | ||
|
|
||
| ## Adding authors | ||
|
|
||
| Create `.md` file in the `content/authors` folder. | ||
|
|
||
| Write front matter in the following format: | ||
|
|
||
| ```yml | ||
| path: ../authors/relative_path_to_file.md | ||
| name: Author's Name | ||
| avatar: /uploads/avatar.jpeg | ||
| ``` | ||
| - `path` - **Required.** String that the CMS will insert to the author field in | ||
| the blog post. Should be equal to the path from the blog post to the author's | ||
| `.md` file. | ||
| - `name` – **Required.** Author's name. | ||
| - `avatar` - **Required.** Relative path to the author's avatar (1024x1024 is | ||
| recommended). |
Oops, something went wrong.