]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | This provides guidance on how to contribute various content to `rocksdb.org`. |
2 | ||
3 | ## Getting started | |
4 | ||
5 | You should only have to do these one time. | |
6 | ||
7 | - Rename this file to `CONTRIBUTING.md`. | |
8 | - Rename `EXAMPLE-README-FOR-RUNNING-DOCS.md` to `README.md` (replacing the existing `README.md` that came with the template). | |
9 | - Rename `EXAMPLE-LICENSE` to `LICENSE`. | |
10 | - Review the [template information](./TEMPLATE-INFORMATION.md). | |
11 | - Review `./_config.yml`. | |
12 | - Make sure you update `title`, `description`, `tagline` and `gacode` (Google Analytics) in `./_config.yml`. | |
13 | ||
14 | ## Basic Structure | |
15 | ||
16 | Most content is written in markdown. You name the file `something.md`, then have a header that looks like this: | |
17 | ||
18 | ``` | |
19 | --- | |
20 | docid: getting-started | |
21 | title: Getting started with ProjectName | |
22 | layout: docs | |
23 | permalink: /docs/getting-started.html | |
24 | --- | |
25 | ``` | |
26 | ||
27 | Customize these values for each document, blog post, etc. | |
28 | ||
29 | > The filename of the `.md` file doesn't actually matter; what is important is the `docid` being unique and the `permalink` correct and unique too). | |
30 | ||
31 | ## Landing page | |
32 | ||
33 | Modify `index.md` with your new or updated content. | |
34 | ||
35 | If you want a `GridBlock` as part of your content, you can do so directly with HTML: | |
36 | ||
37 | ``` | |
38 | <div class="gridBlock"> | |
39 | <div class="blockElement twoByGridBlock alignLeft"> | |
40 | <div class="blockContent"> | |
41 | <h3>Your Features</h3> | |
42 | <ul> | |
43 | <li>The <a href="http://example.org/">Example</a></li> | |
44 | <li><a href="http://example.com">Another Example</a></li> | |
45 | </ul> | |
46 | </div> | |
47 | </div> | |
48 | ||
49 | <div class="blockElement twoByGridBlock alignLeft"> | |
50 | <div class="blockContent"> | |
51 | <h3>More information</h3> | |
52 | <p> | |
53 | Stuff here | |
54 | </p> | |
55 | </div> | |
56 | </div> | |
57 | </div> | |
58 | ``` | |
59 | ||
60 | or with a combination of changing `./_data/features.yml` and adding some Liquid to `index.md`, such as: | |
61 | ||
62 | ``` | |
63 | {% include content/gridblocks.html data_source=site.data.features imagealign="bottom"%} | |
64 | ``` | |
65 | ||
66 | ## Blog | |
67 | ||
68 | To modify a blog post, edit the appopriate markdown file in `./_posts/`. | |
69 | ||
70 | Adding a new blog post is a four-step process. | |
71 | ||
72 | > Some posts have a `permalink` and `comments` in the blog post YAML header. You will not need these for new blog posts. These are an artifact of migrating the blog from Wordpress to gh-pages. | |
73 | ||
74 | 1. Create your blog post in `./_posts/` in markdown (file extension `.md` or `.markdown`). See current posts in that folder or `./doc-type-examples/2016-04-07-blog-post-example.md` for an example of the YAML format. **If the `./_posts` directory does not exist, create it**. | |
75 | - You can add a `<!--truncate-->` tag in the middle of your post such that you show only the excerpt above that tag in the main `/blog` index on your page. | |
76 | 1. If you have not authored a blog post before, modify the `./_data/authors.yml` file with the `author` id you used in your blog post, along with your full name and Facebook ID to get your profile picture. | |
77 | 1. [Run the site locally](./README.md) to test your changes. It will be at `http://127.0.0.1/blog/your-new-blog-post-title.html` | |
78 | 1. Push your changes to GitHub. | |
79 | ||
80 | ## Docs | |
81 | ||
82 | To modify docs, edit the appropriate markdown file in `./_docs/`. | |
83 | ||
84 | To add docs to the site.... | |
85 | ||
86 | 1. Add your markdown file to the `./_docs/` folder. See `./doc-type-examples/docs-hello-world.md` for an example of the YAML header format. **If the `./_docs/` directory does not exist, create it**. | |
87 | - You can use folders in the `./_docs/` directory to organize your content if you want. | |
88 | 1. Update `_data/nav_docs.yml` to add your new document to the navigation bar. Use the `docid` you put in your doc markdown in as the `id` in the `_data/nav_docs.yml` file. | |
89 | 1. [Run the site locally](./README.md) to test your changes. It will be at `http://127.0.0.1/docs/your-new-doc-permalink.html` | |
90 | 1. Push your changes to GitHub. | |
91 | ||
92 | ## Header Bar | |
93 | ||
94 | To modify the header bar, change `./_data/nav.yml`. | |
95 | ||
96 | ## Top Level Page | |
97 | ||
98 | To modify a top-level page, edit the appropriate markdown file in `./top-level/` | |
99 | ||
100 | If you want a top-level page (e.g., http://your-site.com/top-level.html) -- not in `/blog/` or `/docs/`.... | |
101 | ||
102 | 1. Create a markdown file in the root `./top-level/`. See `./doc-type-examples/top-level-example.md` for more information. | |
103 | 1. If you want a visible link to that file, update `_data/nav.yml` to add a link to your new top-level document in the header bar. | |
104 | ||
105 | > This is not necessary if you just want to have a page that is linked to from another page, but not exposed as direct link to the user. | |
106 | ||
107 | 1. [Run the site locally](./README.md) to test your changes. It will be at `http://127.0.0.1/your-top-level-page-permalink.html` | |
108 | 1. Push your changes to GitHub. | |
109 | ||
110 | ## Other Changes | |
111 | ||
112 | - CSS: `./css/main.css` or `./_sass/*.scss`. | |
113 | - Images: `./static/images/[docs | posts]/....` | |
114 | - Main Blog post HTML: `./_includes/post.html` | |
115 | - Main Docs HTML: `./_includes/doc.html` |