Evaluate neofs-spec reuse possibility #15

New issue

Open

opened 2025-12-28 18:11:15 +00:00 by sami · 3 comments

sami commented

2025-12-28 18:11:15 +00:00

Owner

Originally created by @roman-khimov on GitHub (Jan 13, 2023).

See https://github.com/nspcc-dev/neofs-spec/, it has quite some content there, but I'm not sure how easy it is to reuse it for the doc.fs.neo.org. It uses very specific tooling, it has a structure of its own. We need to evaluate this possibility, can this be done, how can this be done, what changes are needed (if any) to make it possible.

Originally created by @roman-khimov on GitHub (Jan 13, 2023). See https://github.com/nspcc-dev/neofs-spec/, it has quite some content there, but I'm not sure how easy it is to reuse it for the doc.fs.neo.org. It uses very specific tooling, it has a structure of its own. We need to evaluate this possibility, can this be done, how can this be done, what changes are needed (if any) to make it possible.

sami added the

enhancement

labels

2025-12-28 18:11:15 +00:00

sami commented

2025-12-28 18:11:15 +00:00

Author

Owner

@mike-petrov commented on GitHub (Jan 13, 2023):

A big plus is that we have the underlying markdown on both github and docsite. All the components look good: tables, code, headers, formatting. Transferring to the docsite shouldn't be a problem, but there are a couple of things here:

Each .md file must have the necessary parameters at the beginning, according to the following structure:

---
title: "API & SDK"
description: "API and SDK implementations"
date: "2023-01-13"
---

Structure of the neofs-spec repository does not allow for good navigation by section. In the case of moving current structure there will be a lot of tabs on one page, which I think it is better to separate.

Relative paths for images are constructed in different ways: pic/acl-basic-private.svg (github), ../pic/acl-basic-private.svg (docsite)

@mike-petrov commented on GitHub (Jan 13, 2023): A big plus is that we have the underlying markdown on both github and docsite. All the components look good: tables, code, headers, formatting. Transferring to the docsite shouldn't be a problem, but there are a couple of things here: 1. Each `.md` file must have the necessary parameters at the beginning, according to the following structure: ``` --- title: "API & SDK" description: "API and SDK implementations" date: "2023-01-13" --- ``` 2. Structure of the [neofs-spec](https://github.com/nspcc-dev/neofs-spec) repository does not allow for good navigation by section. In the case of moving current structure there will be a lot of tabs on one page, which I think it is better to separate. <img width="1097" alt="image" src="https://user-images.githubusercontent.com/32885629/212281369-0c5dff43-aa47-4a51-962e-e47457ef8b05.png"> 3. Relative paths for images are constructed in different ways: `pic/acl-basic-private.svg` (github), `../pic/acl-basic-private.svg` (docsite)

sami commented

2025-12-28 18:11:15 +00:00

Author

Owner

@mike-petrov commented on GitHub (Jan 13, 2023):

There is an idea how to solve the second point without changing the repository structure. Display sections in dropdown form and the ability to switch to any topic (like Nodes section).

@mike-petrov commented on GitHub (Jan 13, 2023): There is an idea how to solve the second point without changing the repository structure. Display sections in dropdown form and the ability to switch to any topic (like `Nodes` section). <img width="732" alt="image" src="https://user-images.githubusercontent.com/32885629/212287862-371fcf37-21d3-48a8-9bf5-88529ffc303e.png">

sami commented

2025-12-28 18:11:15 +00:00

Author

Owner

@roman-khimov commented on GitHub (Jan 15, 2023):

Can we include an MD from MD? We may have some "wrapper" MDs here that include ones from neofs-spec this way (with neofs-spec residing in some submodule). This will likely solve the second issue as well.

@roman-khimov commented on GitHub (Jan 15, 2023): Can we include an MD from MD? We may have some "wrapper" MDs here that include ones from neofs-spec this way (with neofs-spec residing in some submodule). This will likely solve the second issue as well.