Comments (10)
proposed solution
This tool will expose a set of page templates that have consistent, clear data requirements and let library authors provide the data they need. This tool will also provide a set of markdown helpers that library authors can use in the majority of cases.
Library authors will be responsible for gluing all the pieces together in static.config.js
, and will use getRoutes
directly rather than relying on plugins. So something like this:
import path from "path";
import Document from "./src/html";
import metadata from "./src/constants";
import config from "./src/config"
import { IndexPage, DocsPage, getMarkdownPages, createTOC } from "formidable-oss-landers"
export default {
paths: {
src: "src",
...
},
plugins: [
require.resolve("react-static-plugin-styled-components"),
require.resolve("react-static-plugin-react-router"),
],
Document,
getRoutes: async () => {
const docsPages = getMarkdownPages("./content/docs");
const recipePages = getMarkdownPages("./content/recipes");
const TOC = createTOC([...docsPages, ...recipePages]);
return [
{
path: "/",
template: IndexPage, // might need to have an intermediate copy
getData: () => ({ config })
},
{
path: "/docs",
template: DocsPage,
getData: () => ({ data: docsPages[0].data, config, TOC }),
children: docsPages.slice(1).map((doc, i) => {
return {
path: `/${doc.title}`,
getData: () => ({ data: doc.data, config, TOC }),
template: DocsPage
};
})
}
]
},
getSiteData: () => ({
title: metadata.title,
}),
};
from formidable-oss-landers.
@paulathevalley It seems promising so far. I'm basically just using it to parse a single document with various headings and subheadings into some structured json. I'll keep playing with it and see how it handles a real-world example.
from formidable-oss-landers.
In general I think whatever we use should just be for handling the data, and leave the rendering up to the component. I think the TOC is one of the places where the docs might diverge the most, and it would be great to give library authors the change to mutate the TOC data early. What do you think about a format like this:
[
{ title: "Components", depth: 2 }, // I'm not a link, just a heading
{ title: "VictoryArea", slug: "/docs/victory-area", depth: 3 },
...
]
from formidable-oss-landers.
My only concern with that structure is it might be a little tricky to render. I was leaning toward something like this:
{
"name": "file-name.md",
"depth": 0,
"slug": "file-name",
"link": "/docs/file-name",
"children": [
{
"name": "An H1 Heading",
"depth": 1,
"slug": "an-h1-heading",
"link": "/docs/file-name#an-h1-heading",
"children": [
{
"name": "An H2 Heading",
"depth": 2,
"slug": "an-h2-heading",
"link": "/docs/file-name#an-h2-heading",
"children": []
},
{
"name": "Another H2 Heading",
"depth": 2,
"slug": "another-h2-heading",
"link": "/docs/file-name#another-h2-heading",
"children": []
},
{
"name": "A Third H2 Heading",
"depth": 2,
"slug": "a-third-h2-heading",
"link": "/docs/file-name#a-third-h2-heading",
"children": []
}
]
},
{
"name": "Another H1 Heading",
"depth": 1,
"slug": "another-h1-heading",
"link": "/docs/file-name#another-h1-heading",
"children": [
{
"name": "An H2 Heading",
"depth": 2,
"slug": "an-h2-heading",
"link": "/docs/file-name#an-h2-heading",
"children": []
}
]
}
]
}
I threw together a quick parser that generates that structure without any libraries, since I think a recursive List
component might be simpler with this nested structure than working with a flat array. What do you think, @paulathevalley ?
from formidable-oss-landers.
Any thoughts on how we should structure the TOC
object? I found this library, which seems promising. Not sure if we'd want something like that to handle the rendering as well or if we just want the json.
from formidable-oss-landers.
@treyhoover I don't have any ideas on the structure. I'm sure it's possible to create a component that can turn whatever structure it is into nested lists. Just need to know what nests where.
I'm not really sure how to evaluate a library. What are the pros/cons? Does it make your life easier? How does it handle various types of nested directories? Would it help to look up examples of how markdown files are currently nested and mimic them in your example? idk if this is all stuff you already know or if it's helping...
from formidable-oss-landers.
Here's a kind of ugly thing we did with remark for victory-docs, but this is more for the headings TOC than the file / directory based TOC.
https://github.com/FormidableLabs/victory/blob/main/docs/static-config-helpers/get-md-files.js#L40
from formidable-oss-landers.
You're right, that looks better. Two other mior things to consider. 1) there should be a way to limit the depth of what ends up in the sidebar 2) There should be a way to alter the order of the children, maybe via a field in the yaml?
from formidable-oss-landers.
Setting a max depth should be easy enough! This structure is just for the individual file, so that order should be fine based on the order of the headings themselves. But when combining multiple markdown files, I just have it sorting via the order
property in the yaml front-matter of each file 🙂
from formidable-oss-landers.
Perfect!
from formidable-oss-landers.
Related Issues (11)
- Add simple react-static app as a demo
- separate example configs and assets from the rest HOT 2
- export template and some supporting components like `Preview` HOT 2
- set up linting and prettier
- Docs sidebar should include search functionality
- Add Parent Header to Docs Slug
- Update Footer Styling for Smaller Screens
- Render `react-live` Content
- Indent Sidebar Subtopics
- Pull Additional Formidable Open Source Info
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from formidable-oss-landers.