|
| 1 | +<p align="center"><img src="https://i2.wp.com/ceph.io/wp-content/uploads/2016/07/Ceph_Logo_Standard_RGB_120411_fa.png?resize=322%2C148&ssl=1" alt="Ceph" /></p> |
| 2 | + |
| 3 | +# Case studies |
| 4 | + |
| 5 | +## Page data |
| 6 | + |
| 7 | +At the beginning of all case studies, there's a block of data wrapped with ---. This is called frontmatter, and defines data specific to that page in the site. |
| 8 | + |
| 9 | +The frontmatter data is written in [YAML format](https://yaml.org/) using `key: value` pairs. Frontmatter for the case study pages follows a specific schema: |
| 10 | + |
| 11 | +```yaml |
| 12 | +--- |
| 13 | +title: Case study title |
| 14 | +image: "/assets/image.jpg" |
| 15 | +sponsor: |
| 16 | + name: name |
| 17 | + logo: "/assets/logo.png" |
| 18 | + website: "https://www.website.com" |
| 19 | +tags: |
| 20 | + - taxonomy |
| 21 | + - taxonomy |
| 22 | +--- |
| 23 | + |
| 24 | +``` |
| 25 | + |
| 26 | +- `title` (String) — Determines the link text as it appears in the case study navigation card. Also used as the `<title>` for the page.\* |
| 27 | +- `image` (Asset path) — Determines the image shown in the case study navigation card and the hero image beneath the title on the case study page. |
| 28 | +- `sponsor` (Array) - This is an array of values that all contribute to the sponsor information on the case study page. |
| 29 | + - `name` (String) - Determines the sponsor name as it appears in the case study page.\* |
| 30 | + - `logo` (Asset path) - Determines the sponsor logo shown in the case study page. |
| 31 | + - `website` (URL) - Determines the URL for the sponsor’s website. This is applied to the sponsor logo and button shown in the case study page. |
| 32 | +- `tags` (Array) - This is an array of values that determine the taxonomy of the case study page. |
| 33 | + - (String) - Choose from a pre-defined selection of values that apply only to case studies. You can apply as many values as required.\* |
| 34 | + |
| 35 | +\* Careful with any strings that include a colon `:`, as YAML uses this as the key-value pair delimiter. If the title needs to include colons, wrap the `title` string in double-quote marks `"` to ensure it renders as intended. E.g. |
| 36 | + |
| 37 | +```yaml |
| 38 | +title: "Storage or: How I Learned to Stop Worrying and Love Ceph" |
| 39 | +``` |
| 40 | +
|
| 41 | +## Authoring pages |
| 42 | +
|
| 43 | +While the case study pages are all composed in Markdown `.md` files, there are a few bonus features. |
| 44 | + |
| 45 | +### Markdown and HTML |
| 46 | + |
| 47 | +Pages can contain a mix of Markdown and HTML. This means we can intersperse basic content formatting with more bespoke HTML elements in the same file. |
| 48 | + |
| 49 | +``` |
| 50 | +# Page title |
| 51 | + |
| 52 | +A paragraph of text, Markdown style. |
| 53 | + |
| 54 | +- Markdown list items |
| 55 | +- Lists are great |
| 56 | + |
| 57 | +<article class="bespoke"> |
| 58 | + <h2>Stick to HTML</h2> |
| 59 | +</article> |
| 60 | +``` |
| 61 | +
|
| 62 | +The **caveat** here is to ensure that there is always a clear break between Markdown and HTML elements. Mixing and matching the two in a single content block will not work. |
| 63 | +
|
| 64 | +``` |
| 65 | +<!-- This won't work --> |
| 66 | +<article> |
| 67 | + ## Trying for a Markdown heading (and failing) |
| 68 | +</article> |
| 69 | + |
| 70 | +<!-- This will --> |
| 71 | +<article> |
| 72 | + |
| 73 | +## All good here |
| 74 | + |
| 75 | +</article> |
| 76 | +``` |
| 77 | +
|
| 78 | +To learn more about what's possible in Markdown, see [Markdown Guide](https://www.markdownguide.org). |
| 79 | +
|
| 80 | +### Adding links |
| 81 | +
|
| 82 | +Linking to pages throughout the site works in the same way as linking to pages in standard HTML sites. |
| 83 | +
|
| 84 | +We'll most likely be using Markdown's link syntax to link to pages. The links we choose can be relative or absolute. |
| 85 | +
|
| 86 | +If we were on a _case-studies_ page (`/case-studies/case-study`), we could link to another case study page in two ways: |
| 87 | +
|
| 88 | +```md |
| 89 | +[Relative link to case study](../case-study/) |
| 90 | +
|
| 91 | +[Root relative link to case study](/case-studies/case-study/) |
| 92 | +``` |
| 93 | + |
| 94 | +If we need to link to another section/page within the site we can use either method shown above. The `../` prefix can be used to traverse further up the site tree: |
| 95 | + |
| 96 | +```md |
| 97 | +[Relative link to my parent](../) |
| 98 | +[Relative link to my grandparent](../../) |
| 99 | +[Relative link to a sibling of mine](../sibling-page/) |
| 100 | +``` |
| 101 | + |
| 102 | +Note: these don't need filename `.md`/`.html` extensions. |
| 103 | + |
| 104 | +Only use absolute URLs for links out of the site: |
| 105 | + |
| 106 | +```md |
| 107 | +[Absolute link to Ceph.io](https://ceph.io/) |
| 108 | +``` |
| 109 | + |
| 110 | +## Dynamic values |
| 111 | + |
| 112 | +We can interpolate these dynamic values throughout the Markdown. For example, we can save ourselves repeating the page's `title` property for our page title heading by using the `{{ }}` syntax: |
| 113 | + |
| 114 | +```md |
| 115 | +--- |
| 116 | +title: Don't repeat yourself |
| 117 | +--- |
| 118 | + |
| 119 | +# Don't repeat yourself |
| 120 | +``` |
| 121 | + |
| 122 | +becomes: |
| 123 | + |
| 124 | +```md |
| 125 | +--- |
| 126 | +title: Don't repeat yourself |
| 127 | +--- |
| 128 | + |
| 129 | +# {{ title }} |
| 130 | +``` |
| 131 | + |
| 132 | +## Case study structure |
| 133 | + |
| 134 | +The contents of the case studies can all be found in the `src/locale/solutions/case-studies/` directory. Any folder/page created within this directory will generate a web page in the site. |
| 135 | + |
| 136 | +### Folders and file naming |
| 137 | + |
| 138 | +| Input File | Output URL | |
| 139 | +| ------------------------------------------------------ | ------------------------------------------ | |
| 140 | +| /src/locale/solutions/case-studies/case-study/index.md | /locale/solutions/case-studies/case-study/ | |
0 commit comments