This repository was archived by the owner on Jul 1, 2024. It is now read-only.
WIP: General site reorganization #65
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The "getting started" section will be a bit more robust. Some documents have moved here, but they all need to be rewritten to work better together. "Integration guides is getting a bit thinner. (And may need to be renamed?)
… of GitHub version)
|
@irisli I just realized that https://github.com/stellar/developers/blob/master/gulp/extract.js doesn't seem to do anything (there are no directories named |
|
Marked (used by metalsmith-markdown) appears to have issues with code blocks inside elements (as used in my multi-language code examples in stellar-deprecated/docs#136 (see markedjs/marked#596) Might need to switch markdown parsers, change the way we mark up those code examples, or come up with some other crazy workaround. (Would love any thoughts you have on this, @irisli.) |
|
@Mr0grog For the extract.js, we originally wanted the horizon example files to live separately from the markdown files, but it turned out to be too much of a hassle. But we never removed that code. As for switching markdown parsers, I'd be fine with that. We could also try to write a custom handler for code blocks in marked. But that might be too much work. |
Marked was no longer actively maintained and had several bugs the new docs were hitting. The other good option here is Remark, which is a bit slower but more flexible.
(Used for the "Get Started" section)
|
New stuff here:
|
|
@irisli The plugin for adding IDs to headers for the new Markdown parser has support for creating the type of links you're making in JavaScript right now: 5346772#diff-ba210a9157252cc983268fdc3aa3ed52R97 Is there a particular reason to do it in JS, or would it be better to switch over to creating them at build time? |
|
@Mr0grog For the headers, as long as it can generate something that will work like how it currently works, then we can switch to it. It might even be better since my current script does not support headers with links |
|
@iris cool, if you just uncomment those lines and remove your script, I think it ought to work pretty much just the same. Give it a try and let me know. |
Consolidate landing-page-redesign and nav-restructure branches
|
@Mr0grog Your markdownit anchor linker works better than my old script. I uncommented it out and removed my old one |
This was referenced Jul 1, 2016
|
Here is a list of the URL changes: |
|
There is a link with no new counterpart: /developers/learn/integration-guides/building-blocks/account-management.html |
|
👍 now on production |
|
Seems stable on production. Merging now to make things simpler |
Mr0grog
added a commit
that referenced
this pull request
Jul 14, 2016
Styling fixes that should have been in #65
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Work-in-progress; not remotely ready for merging. Also note: there is a corresponding branch in docs: https://github.com/stellar/docs/tree/nav-restructure
This is the basics of reorganizing the developer portal’s content. It doesn’t [yet?] attempt to redesign the general layout of pages. There will probably be some new content coming in here (should those be separate PRs that merge into this one instead of master?), but there isn’t any of that yet. This mainly follows ideas outlined in the “Landing Page - Developers” Google doc. See also the “developers” list on the “integrator flow” Trello board.
This changes the main navigation to the following sections:
- **Guides:** walkthroughs, tutorials, and general narrative documentation about how to build things on/with Stellar. _Much of the Horizon and Core documentation has moved out from here to other sections, so this is slimmer than the old “learn” section._ - **API Reference:** reference documentation about all APIs one might use when writing software that uses Stellar. This primarily means the Horizon’s REST API, but it also includes reference documentation for all the SDKs. - All the horizon docs that used to be in “learn” are now here. Some of these should probably be re-written or cleaned up—the errors overview, for example, should fit better with the list of detailed documents for each error response type. - The JS SDK has several documents here, but the other SDKs have none. At a minimum, each SDK should probably have: 1. Super basic explanation and system requirements (e.g. requires version 0.10+ of Node) 2. Install instructions 3. A basic example of importing the library and doing something with it (e.g. checking an account or doing a transaction—ideally, all SDKs would use the same example) 4. Link to API documentation 5. Link to source repository 6. How/where to submit bugs 7. License information In an ideal world, this might just be the README for each project, though they do not all meet the above requirements. The pages for Ruby, Python, and C# should also be _very_ clear that they are not maintained by Stellar.org (maybe a big colored ribbon at the top or some other hard-to-miss visual indicator). - **Software:** Software/applications provided by Stellar.org that you can install and run, e.g. Core, Horizon, Bridge Server, etc. In a better future, each of these will probably have additional documentation on the dev portal, but for now, most of them (save Core) just link to Github. - **Tools:** Software tools (and example code) you might use as a developer. This is primarily just the laboratory. ## Other NotesThis is pretty tightly linked to corresponding changes under the
nav-restructurebranch on docs. In general, I suspect these two repositories are somewhat tightly linked; it might be better to include the docs repo as either a git submodule or an NPM module to simplify keeping them in sync. (@jedmccaleb, @irisli)Lots more work needs to come in here on rewriting—mainly in the “guides” section:
(The existing guides are mostly just the “how to do a transaction” document that needs to be in “getting started” above.
General Questions