Add templates to doc pages and give docs home one #1268
Conversation
- Default docs page template moved from `src/templates/doc-home.tsx` to `src/templates/doc.tsx`. A new homepage-specific (but currently identical) template has been added in its place. - Added frontmatter to docs home source to define the template - Docs now have a "template" field, which when defined changes the component used to make its page. This is a file relative to `src/templates` with the extension left off. This defaults to `doc`, or the file `src/templates/doc.tsx`. This is not currently on blog posts.
|
@rogermparent what is the plan moving forward? I'm not sure how will we connect MD with this custom template. What kind of customization it will allow us? |
|
The path forward from here is very open and subjective, as we have full freedom on how to connect the docs home's metadata with the new copied component. Given a simple "blocks and some text content" layout, there's three broad directions we can take: 1. Define the homepage "blocks" in frontmatter, rendering them programmatically in the component. Pros:
Cons:
2. Lean on the template component for everything that isn't the body text. Pros:
Cons:
3. Use custom Pros:
Cons:
I suppose it's a little obvious that I'm most for using the |
|
@rogermparent if we go all components, will we need the md file at all? will it have empty body? Also, if we go all components - will we still (on a component level) use Markdown component to render block of texts? Probably, would be useful at this point to see an example? |
Using custom components is one of the only options that keeps content in the body. The text content with this method is written in the markdown file's body as mostly markdown while components are used to wrap special constructs like the home menu blocks.
Absolutely! Making the example is my next top priority right now, I've just been taking it light on the weekend. I'll do one with the component syntax first. |
This is not intended to be final, but show off the general premise of how using custom components for this kind of layout would look like. The card and cards components are, on top of being fully stylable with CSS modules, capable of using arbitrary Markdown images or elements as the card "logo" when the `logo` prop is set to `true` (or anything truthy, like the string `"true"`). This works around the complexity of working in custom image capability by leaning on the one we already have in Markdown. To make a card with a logo, set the "logo" prop to true and make sure the first element in the card contains the image you want- this element will be set aside in its own div, with the rest of the contents displayed beside it using `flex` There are some quirks with Remark custom components, though: - custom components aren't indented - custom components must be contained to one line, including props. - custom components can include Markdown, but there must be an empty line between the transition. - self-closing tags aren't supported Should we use custom components more often, we can migrate to MDX (I actually already have a fully working branch with it that I made on my own time) which handles this syntax much more comfortably because it's designed around the concept. All our custom remark-based logic will cleanly port because MDX actually uses Remark in its pipeline.
| {Array.isArray(children) | ||
| ? children.reduce( | ||
| (acc: Array<object>, child, i) => | ||
| typeof child === 'object' |
There was a problem hiding this comment.
what else can it be ? do we ignore it?
There was a problem hiding this comment.
This filters out the "\n" strings that occur in remark custom component children, as well as anything else that isn't a card, as cards components should only contain card components.
There was a problem hiding this comment.
may be it is safer to raise an exception?
There was a problem hiding this comment.
at least if it something except \n
content/docs/index.md
Outdated
| @@ -1,3 +1,7 @@ | |||
| --- | |||
| template: 'doc-home' | |||
There was a problem hiding this comment.
it looks like we made cards general enough, do we need a separate template now?
There was a problem hiding this comment.
You're right, I expected to need to do something in another component but everything went fine with the new custom components in the body.
I'll remove this template frontmatter and the existing home template. We may need a unique template in the future, but we'll add it when that time comes.
There was a problem hiding this comment.
hey, any update to this? are we removing the template?
There was a problem hiding this comment.
I totally can, and quite quickly, but considering we don't know the exact direction this page is going I haven't committed a change to it yet.
Given my comment on the home issue, I think the best course of action is to temporarily go all-in on the home template and make it a standalone component. This allows us to not be limited in design and get the docs home we want up quickly.
My current plan is that once I get the design I'll make the template that's a React component implementing that design, and once that makes the Docs page match what we want, we merge to master- this first step of the plan lets us get a great docs home out before the important DVC 1.0 events around the corner because the implementation is already here and React components are the easiest to port to any other method down the line.
After we have a page we want made in a simple React component template, we can later quite easily port the page content to something more dev/editor friendly that lets editors change the page in MD.
There was a problem hiding this comment.
@rogermparent I would be happy if we can get something simple and clean like this - https://cube.dev/docs . I don't think we need something too complicated/custom at this point. Does it help to make a decision?
Also, we can take design ideas there (except icons of course :) ) . I'll ask designer after that to make us icons.
| }> = ({ children }) => { | ||
| return ( | ||
| <div className={styles.cards}> | ||
| {Array.isArray(children) |
There was a problem hiding this comment.
I'm still not sure about this - if we have this check, we should have a different type above to my mind ... it is strange that ts-lint complains - any idea why is it happening?
In an effort to make the current solution good enough to fit release, I've removed the alternate template since this branch currently favors custom components.
|
Let's do the following as a next step (to merge it):
After that I'll be able to show this to a designer and get some actual design. |
I'm on it!
Easy enough
Also easy, but we'll have to decide which one takes over for the cards that currently have two.
Similar to the card links, the implementation is easy once we decide on what the titles are. I'll get as far as I can with my own decisions as an example and adapt it when other feedback comes in. |
Cards now accept a `href` prop, which turns the whole card into a link. This is our Link wrapper, so we get the same automatic `rel` and `target` setting for external links as well as Gatsby Link for internal ones. This link spans the whole card, and has some styling to go along with it. Currently the hover style is set to a slight grow animation, but it could be anything. Most of the `children`-modifying hackery has been removed in favor of wrapping all Cards. This also brings a degree of consistency to Cards, and we can apply indivual styles if the need arises. It's still needed for the Card Images, however, since newlines that show up in `children` are mandatory for how rehype's React and MD are separated.
|
Done with the design changes, and the Card components are now more sanely written. |
|
@jorgeorpinel let's keep Get started instead on Install and Python API reference instead of Use Cases (use cases are not ready to be honest to put them here)? |
|
@rogermparent : (sorry for pixel movements again) - let's for now do the same effect as we have for buttons to the right? It might be enough and will look consistent (I'll ask for icons after we decide on the content with @jorgeorpinel ) |
Now they match the right side buttons, aside from the animated transition.
|
@shcheklein I changed the Card hover animation to only The cube.dev example has their cards start dark and brighten, while ours start bright and darken. We could invert the color, but I feel like there's too much contrast between the current two colors to do that- maybe we could use a shade of gray only barely below white, and a blue hue like the buttons' hover color to keep some consistency. |
Co-authored-by: Restyled.io <[email protected]>
|
Done! Last step - ping designer to make it look better. Thanks @rogermparent ! |
|
|
||
| <card href="/doc/user-guide" heading="User Guide"> | ||
|
|
||
| Study the detailed inner-workings of DVC in its user guide |
There was a problem hiding this comment.
Super minimal: Missing period. I'll add it no worries. Same in cmd ref card text
This branch is now at the point where docs have configurable templates and the docs home has a unique template at
src/templates/doc-home.tsxas opposed to regular docs which usesrc/templates/doc.tsx(before, both useddoc-home).Now that the scaffolding is there, we just have to actually make the page.
Default docs page template moved from
src/templates/doc-home.tsxtosrc/templates/doc.tsx. A new homepage-specific (but currently identical)template has been added in its place.
Added frontmatter to docs home source to define the template
Docs now have a "template" field, which when defined changes the component
used to make its page. This is a file relative to
src/templateswith theextension left off. This defaults to
doc, or the filesrc/templates/doc.tsx. This is not currently on blog posts.